React Integration

@near-kit/react provides thin, focused React hooks that wrap the core near-kit library. These hooks handle the React lifecycle for you while giving you full control over caching and data fetching strategies.

Design Philosophy: These hooks are intentionally thin wrappers. They manage loading states and errors, but don’t include built-in caching. For production apps, we recommend pairing them with React Query or SWR.

Installation

npm install @near-kit/react

bun add @near-kit/react

yarn add @near-kit/react

pnpm add @near-kit/react

@near-kit/react includes near-kit as a dependency — both packages are versioned together.

Quick Example

Here’s a complete example showing provider setup, reading data, and sending transactions:

import { Near } from "near-kit"
import { NearProvider, useNear, useBalance, useSend } from "@near-kit/react"

// 1. Create the Near client
const near = new Near({
  network: "testnet",
  privateKey: "ed25519:...",
  defaultSignerId: "alice.testnet",
})

// 2. Wrap your app with NearProvider
function App() {
  return (
    <NearProvider near={near}>
      <Wallet />
    </NearProvider>
  )
}

// 3. Use hooks in any component
function Wallet() {
  const { data: balance, isLoading } = useBalance({ accountId: "alice.testnet" })
  const { mutate: send, isPending } = useSend()

  const handleSend = async () => {
    await send("bob.testnet", "1 NEAR")
  }

  if (isLoading) return <p>Loading...</p>

  return (
    <div>
      <p>Balance: {balance}</p>
      <button onClick={handleSend} disabled={isPending}>
        {isPending ? "Sending..." : "Send 1 NEAR"}
      </button>
    </div>
  )
}

For production apps with mutations, we recommend using React Query with useNear() for proper cache invalidation. The thin hooks above are great for prototyping but don’t automatically refetch data after mutations.

Available Hooks

useNear

Access the Near client instance from context

useView

Call view methods on smart contracts

useBalance

Get formatted account balance

useAccountExists

Check if an account exists

useCall

Call contract methods that modify state

useSend

Send NEAR tokens to another account

useAccount

Get full account details and access keys

useContract

Get a typed contract interface

Hook Categories

Read Hooks
Mutation Hooks

These hooks fetch data from the blockchain. They return { data, error, isLoading, refetch }.

// View method call
const { data: messages } = useView<Message[]>({
  contractId: "guestbook.near",
  method: "get_messages",
  args: { limit: 10 },
})

// Account balance
const { data: balance } = useBalance({ accountId: "alice.near" })

// Account existence check
const { data: exists } = useAccountExists({ accountId: "bob.near" })

// Full account details (connected wallet account)
const { data: account } = useAccount()

These hooks modify blockchain state. They return { mutate, isPending, error, data, reset }.

// Send tokens
const { mutate: send, isPending } = useSend()
await send("bob.near", "5 NEAR")

// Call contract method
const { mutate, isPending: isCallPending } = useCall({
  contractId: "counter.near",
  method: "increment",
})
await mutate({})

What’s Next?

Provider Setup

Configure the NearProvider for your app

Hooks Reference

Complete API reference for all hooks

Data Fetching

Integrate with React Query or SWR

Wallet Connection

Connect user wallets in the browser

Getting Started

Essentials

React

Building dApps

Advanced

Reference

React Integration

Installation

Quick Example

Available Hooks

useNear

useView

useBalance

useAccountExists

useCall

useSend

useAccount

useContract

Hook Categories

What’s Next?

Provider Setup

Hooks Reference

Data Fetching

Wallet Connection

​Installation

​Quick Example

​Available Hooks

useNear

useView

useBalance

useAccountExists

useCall

useSend

useAccount

useContract

​Hook Categories

​What’s Next?

Provider Setup

Hooks Reference

Data Fetching

Wallet Connection

Installation

Quick Example

Available Hooks

Hook Categories

What’s Next?