) => {
+ event.preventDefault();
+ try {
+ setAddress(toNormalizedAddress(input.trim()));
+ setInputError(null);
+ } catch (err) {
+ setInputError(err instanceof Error ? err.message : "Invalid EVM address.");
+ }
+ };
+
+ return (
+
+ Primary Name
+
+ Resolves the ENSIP-19 Primary Name for an address on a selected chain using{" "}
+ usePrimaryName. Because ENSIP-19 is multichain, pick which chain's primary name
+ you want to read.
+
+
+
+
+ {isLoading && Loading…
}
+ {error && Error: {error.message}
}
+ {data && (
+
+ Primary Name: {data.name ?? "(none)"}
+
+ )}
+
+ );
+}
diff --git a/packages/ensnode-react/example/src/components/IndexingStatusBadge.tsx b/packages/ensnode-react/example/src/components/IndexingStatusBadge.tsx
new file mode 100644
index 0000000000..e1cfff9148
--- /dev/null
+++ b/packages/ensnode-react/example/src/components/IndexingStatusBadge.tsx
@@ -0,0 +1,54 @@
+import type { Duration, UnixTimestamp } from "enssdk";
+
+import { useIndexingStatus } from "@ensnode/ensnode-react";
+import { EnsApiIndexingStatusResponseCodes } from "@ensnode/ensnode-sdk";
+
+function formatWorstCaseDistance(distance: Duration): string {
+ if (distance <= 60) return `${distance}s behind`;
+ if (distance <= 60 * 60) return `${Math.round(distance / 60)}m behind`;
+ if (distance <= 60 * 60 * 24) return `${Math.round(distance / (60 * 60))}h behind`;
+ return `${Math.round(distance / (60 * 60 * 24))}d behind`;
+}
+
+function formatSnapshotAge(snapshotTime: UnixTimestamp, now: UnixTimestamp): string {
+ const age = Math.max(0, now - snapshotTime);
+ if (age < 60) return `${age}s ago`;
+ if (age < 60 * 60) return `${Math.round(age / 60)}m ago`;
+ return `${Math.round(age / (60 * 60))}h ago`;
+}
+
+/**
+ * Compact indexing-status indicator inspired by the ENSAdmin `ProjectionInfo` info-icon.
+ *
+ * Polls the connected ENSNode's `/api/indexing-status` endpoint (via
+ * `useIndexingStatus`) and renders the worst-case projection distance plus
+ * snapshot freshness so consumers can see at a glance how far behind realtime
+ * the connected ENSNode is.
+ */
+export function IndexingStatusBadge() {
+ const { data, isLoading, error } = useIndexingStatus();
+
+ if (isLoading) {
+ return ;
+ }
+
+ if (error) {
+ return ;
+ }
+
+ if (!data || data.responseCode !== EnsApiIndexingStatusResponseCodes.Ok) {
+ return ;
+ }
+
+ const { projectedAt, worstCaseDistance, snapshot } = data.realtimeProjection;
+
+ return (
+
+ );
+}
diff --git a/packages/ensnode-react/example/src/components/RequireActiveConnection.tsx b/packages/ensnode-react/example/src/components/RequireActiveConnection.tsx
new file mode 100644
index 0000000000..ed34b36096
--- /dev/null
+++ b/packages/ensnode-react/example/src/components/RequireActiveConnection.tsx
@@ -0,0 +1,92 @@
+import type { ReactNode } from "react";
+
+import { useIndexingStatus } from "@ensnode/ensnode-react";
+import { EnsApiIndexingStatusResponseCodes } from "@ensnode/ensnode-sdk";
+
+import { ENSNODE_URL, EXPECTED_NAMESPACE } from "../config";
+import { classifyConnectionError } from "../lib/classify-connection-error";
+
+interface RequireActiveConnectionProps {
+ children: ReactNode;
+}
+
+/**
+ * Protects child rendering on a healthy, namespace-matching ENSNode connection.
+ *
+ * Modeled after ENSAdmin's `RequireActiveConnection`
+ * (`apps/ensadmin/src/components/connections/require-active-connection.tsx`),
+ * with the additional namespace-mismatch check required by this example app.
+ *
+ * Failure modes are intentionally disambiguated so the UI can tell apart a
+ * network-level problem from an application-level problem:
+ *
+ * 1. `useIndexingStatus` throws (fetch failed, server returned an error response,
+ * or the response failed deserialization) `classifyConnectionError` decides
+ * whether to call this a `network` or `application` failure.
+ * 2. The server answered with `responseCode === "error"` surfaced as an
+ * application-level "ENSNode reported its indexing status is unavailable" state.
+ * 3. The response is OK but `stackInfo.ensIndexer.namespace` does not match
+ * `EXPECTED_NAMESPACE` surfaced as an `unsupported-namespace` mismatch and
+ * the connection is refused.
+ *
+ * Only once we've confirmed (1) we can reach ENSNode, (2) it returned a usable
+ * config, and (3) the namespace matches, do we render `children`.
+ */
+// TODO: candidate for promotion to `enskit` as it duplicates `apps/ensadmin/src/components/connections/require-active-connection.tsx`
+export function RequireActiveConnection({ children }: RequireActiveConnectionProps) {
+ const { data, isLoading, error } = useIndexingStatus();
+
+ if (isLoading) {
+ return (
+
+ Connecting to ENSNode at {ENSNODE_URL.href}…
+
+ );
+ }
+
+ if (error) {
+ const failure = classifyConnectionError(error);
+ return (
+
+ Connection failed ({failure.kind})
+ {failure.message}
+
+ Configured ENSNode: {ENSNODE_URL.href}
+
+
+ );
+ }
+
+ if (!data || data.responseCode === EnsApiIndexingStatusResponseCodes.Error) {
+ return (
+
+ Connection failed (application)
+
+ ENSNode answered, but reported that its indexing status is currently unavailable. The
+ instance may still be starting up or its dependencies (ENSDb, ENSIndexer) are not yet
+ healthy.
+
+
+ );
+ }
+
+ const actualNamespace = data.stackInfo.ensIndexer.namespace;
+ if (actualNamespace !== EXPECTED_NAMESPACE) {
+ return (
+
+ Connection refused (unsupported-namespace)
+
+ This example app was built for ENS namespace {EXPECTED_NAMESPACE}, but the
+ ENSNode at {ENSNODE_URL.href} is indexing namespace{" "}
+ {actualNamespace}.
+
+
+ Re-run with VITE_ENS_NAMESPACE={actualNamespace} or point{" "}
+ VITE_ENSNODE_URL at an instance indexing {EXPECTED_NAMESPACE}.
+
+
+ );
+ }
+
+ return <>{children};
+}
diff --git a/packages/ensnode-react/example/src/config.ts b/packages/ensnode-react/example/src/config.ts
new file mode 100644
index 0000000000..4a09a09af4
--- /dev/null
+++ b/packages/ensnode-react/example/src/config.ts
@@ -0,0 +1,13 @@
+import { type ENSNamespaceId, ENSNamespaceIds } from "@ensnode/datasources";
+import { ENSNamespaceSchema, makeUrlSchema } from "@ensnode/ensnode-sdk/internal";
+
+// TODO: potential internal to be made public
+const DEFAULT_ENSNODE_URL = "https://api.alpha.green.ensnode.io";
+
+export const ENSNODE_URL: URL = makeUrlSchema("VITE_ENSNODE_URL").parse(
+ import.meta.env.VITE_ENSNODE_URL ?? DEFAULT_ENSNODE_URL,
+);
+
+export const EXPECTED_NAMESPACE: ENSNamespaceId = ENSNamespaceSchema.parse(
+ import.meta.env.VITE_ENS_NAMESPACE ?? ENSNamespaceIds.Mainnet,
+);
diff --git a/packages/ensnode-react/example/src/lib/classify-connection-error.ts b/packages/ensnode-react/example/src/lib/classify-connection-error.ts
new file mode 100644
index 0000000000..0d7fad70c6
--- /dev/null
+++ b/packages/ensnode-react/example/src/lib/classify-connection-error.ts
@@ -0,0 +1,27 @@
+export type ConnectionFailureKind = "network" | "application" | "unsupported-namespace";
+
+export interface ConnectionFailure {
+ kind: ConnectionFailureKind;
+ message: string;
+}
+
+// TODO: abstract out
+export function classifyConnectionError(error: unknown): ConnectionFailure {
+ if (error instanceof TypeError) {
+ return {
+ kind: "network",
+ message:
+ "Could not reach the ENSNode instance. " +
+ "Check the URL, your network, and that the server allows CORS from this origin.",
+ };
+ }
+
+ if (error instanceof Error) {
+ return { kind: "application", message: error.message };
+ }
+
+ return {
+ kind: "application",
+ message: "Unknown error connecting to ENSNode.",
+ };
+}
diff --git a/packages/ensnode-react/example/src/main.tsx b/packages/ensnode-react/example/src/main.tsx
new file mode 100644
index 0000000000..4a1253371e
--- /dev/null
+++ b/packages/ensnode-react/example/src/main.tsx
@@ -0,0 +1,6 @@
+import { createRoot } from "react-dom/client";
+
+import { App } from "./App";
+
+// biome-ignore lint/style/noNonNullAssertion: the #root element definitely exists (see index.html)
+createRoot(document.getElementById("root")!).render();
diff --git a/packages/ensnode-react/example/src/vite-env.d.ts b/packages/ensnode-react/example/src/vite-env.d.ts
new file mode 100644
index 0000000000..c04205cedd
--- /dev/null
+++ b/packages/ensnode-react/example/src/vite-env.d.ts
@@ -0,0 +1,10 @@
+///
+
+interface ImportMetaEnv {
+ readonly VITE_ENSNODE_URL?: string;
+ readonly VITE_ENS_NAMESPACE?: string;
+}
+
+interface ImportMeta {
+ readonly env: ImportMetaEnv;
+}
diff --git a/packages/ensnode-react/example/tsconfig.json b/packages/ensnode-react/example/tsconfig.json
new file mode 100644
index 0000000000..0192fe334b
--- /dev/null
+++ b/packages/ensnode-react/example/tsconfig.json
@@ -0,0 +1,13 @@
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "bundler",
+ "jsx": "react-jsx",
+ "strict": true,
+ "esModuleInterop": true,
+ "skipLibCheck": true,
+ "lib": ["ESNext", "DOM", "DOM.Iterable"]
+ },
+ "include": ["src"]
+}
diff --git a/packages/ensnode-react/example/vite.config.ts b/packages/ensnode-react/example/vite.config.ts
new file mode 100644
index 0000000000..58676f788a
--- /dev/null
+++ b/packages/ensnode-react/example/vite.config.ts
@@ -0,0 +1,6 @@
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+ plugins: [react()],
+});
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 469f7f3d7e..631915dac7 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1026,6 +1026,43 @@ importers:
specifier: 'catalog:'
version: 4.0.5(@types/debug@4.1.12)(@types/node@24.10.9)(jiti@2.6.1)(jsdom@27.0.1(postcss@8.5.12))(lightningcss@1.30.2)(tsx@4.21.0)(yaml@2.8.3)
+ packages/ensnode-react/example:
+ dependencies:
+ '@ensnode/datasources':
+ specifier: workspace:*
+ version: link:../../datasources
+ '@ensnode/ensnode-react':
+ specifier: workspace:*
+ version: link:..
+ '@ensnode/ensnode-sdk':
+ specifier: workspace:*
+ version: link:../../ensnode-sdk
+ enssdk:
+ specifier: workspace:*
+ version: link:../../enssdk
+ react:
+ specifier: 'catalog:'
+ version: 19.2.1
+ react-dom:
+ specifier: 'catalog:'
+ version: 19.2.1(react@19.2.1)
+ devDependencies:
+ '@types/react':
+ specifier: 'catalog:'
+ version: 19.2.7
+ '@types/react-dom':
+ specifier: 'catalog:'
+ version: 19.2.3(@types/react@19.2.7)
+ '@vitejs/plugin-react':
+ specifier: ^4.5.2
+ version: 4.7.0(vite@7.3.2(@types/node@24.10.9)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)(yaml@2.8.3))
+ typescript:
+ specifier: 'catalog:'
+ version: 5.9.3
+ vite:
+ specifier: 'catalog:'
+ version: 7.3.2(@types/node@24.10.9)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)(yaml@2.8.3)
+
packages/ensnode-sdk:
dependencies:
'@ensdomains/address-encoder':
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 57cbd0d031..e6dd7f889b 100644
--- a/pnpm-workspace.yaml
+++ b/pnpm-workspace.yaml
@@ -3,6 +3,8 @@ packages:
- docs/*
- examples/*
- packages/*
+ # TODO: remove once we can move into `examples` folder enskit-example
+ - packages/ensnode-react/example
catalog:
"@adraffy/ens-normalize": 1.11.1