Skip to main content
The NearProvider component makes a Near client instance available to all components in your app via React Context.

​
Basic Setup

1

Create the Near client

Create your Near instance with your desired configuration. This can be done outside your component tree.
import { Near } from "near-kit"

const near = new Near({
  network: "mainnet",
})
2

Wrap your app with NearProvider

Place the NearProvider at the root of your component tree.
import { NearProvider } from "@near-kit/react"

function App() {
  return (
    <NearProvider near={near}>
      <YourApp />
    </NearProvider>
  )
}
3

Use hooks in any component

All hooks from @near-kit/react will now have access to the Near client.
import { useBalance } from "@near-kit/react"

function WalletDisplay() {
  const { data: balance } = useBalance({ accountId: "alice.near" })
  return <p>Balance: {balance}</p>
}

​
Provider Props

​
near
Near
required
The Near client instance to provide to all child components.
​
children
ReactNode
required
React children to render inside the provider.

​
useNear Hook

Access the Near client directly when you need the full API: 
import { useNear } from "@near-kit/react"

function AdvancedComponent() {
  const near = useNear()

  const handleComplex = async () => {
    // Full access to the Near client API
    const result = await near
      .transaction("alice.near")
      .functionCall("contract.near", "method", { arg: "value" })
      .transfer("bob.near", "1 NEAR")
      .send()
  }

  return <button onClick={handleComplex}>Complex Transaction</button>
}
useNear() will throw an error if called outside of a NearProvider. Always ensure your components are wrapped.

​
Framework-Specific Setup

Create a client component for the provider:
// providers/near-provider.tsx
"use client"

import { Near } from "near-kit"
import { NearProvider } from "@near-kit/react"

const near = new Near({ network: "mainnet" })

export function NearProviderWrapper({ children }: { children: React.ReactNode }) {
  return <NearProvider near={near}>{children}</NearProvider>
}
Use it in your root layout:
// app/layout.tsx
import { NearProviderWrapper } from "@/providers/near-provider"

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html>
      <body>
        <NearProviderWrapper>{children}</NearProviderWrapper>
      </body>
    </html>
  )
}
The @near-kit/react package includes the "use client" directive, so you don’t need to add it to your imports. However, components using the hooks must be client components.

​
With Wallet Connection

For dApps where users connect their own wallets, create the Near instance dynamically: 
"use client"

import { useState, useEffect } from "react"
import { Near, fromWalletSelector } from "near-kit"
import { NearProvider } from "@near-kit/react"
import { setupWalletSelector } from "@near-wallet-selector/core"

export function WalletProvider({ children }: { children: React.ReactNode }) {
  const [near, setNear] = useState<Near | null>(null)

  useEffect(() => {
    async function init() {
      const selector = await setupWalletSelector({
        network: "mainnet",
        modules: [/* ... */],
      })

      if (selector.isSignedIn()) {
        const wallet = await selector.wallet()
        setNear(
          new Near({
            network: "mainnet",
            wallet: fromWalletSelector(wallet),
          })
        )
      }
    }
    init()
  }, [])

  // Show loading or connect button when not connected
  if (!near) {
    return <ConnectWalletButton />
  }

  return <NearProvider near={near}>{children}</NearProvider>
}
For a complete wallet integration example, see the Frontend Integration guide.

​
Error: Nested Provider

NearProvider throws an error if nested inside another NearProvider. This prevents accidental context shadowing.
// ❌ This will throw an error
<NearProvider near={near1}>
  <NearProvider near={near2}>  {/* Error! */}
    <App />
  </NearProvider>
</NearProvider>

// ✅ Use a single provider at the root
<NearProvider near={near}>
  <App />
</NearProvider>
If you need multiple Near clients (rare), manage them outside of context: 
const mainnetNear = new Near({ network: "mainnet" })
const testnetNear = new Near({ network: "testnet" })

// Use the specific client directly where needed
const balance = await testnetNear.getBalance("alice.testnet")