Pi Network React SDK

This package, pi-sdk-react provides idiomatic React hooks and example components for building apps and integrations on the Pi Network using the browser’s window.Pi API with TypeScript safety and React ergonomics. It is part of the “Ten Minutes to Transactions” effort described in this video.

This package only contains the frontend interface for initiating and completing Pi transactions. It does not include backend support and will not operate without it. Use one of the backend packages such as pi-sdk-nextjs, pi-sdk-express, pi-sdk-express, or pi-sdk-rails.

React Quick Start

Install pi-sdk-react package to your app

npm install pi-sdk-react
yarn add pi-sdk-react

Ensure the global Pi SDK is available

Add in your main app HTML (e.g., public/index.html or via a script/Head component).

<head>
  <!-- ... other <head> content (meta, title, styles, etc.) ... -->
  <script src="https://sdk.minepi.com/pi-sdk.js"></script>
</head>

This is required for all Pi SDK browser integrations.

Use the hooks and components in your app

import React from 'react';
import { usePiConnection, usePiPurchase } from 'pi-sdk-react';
import { PaymentData } from 'pi-sdk-js';

const defaultPaymentData: PaymentData = {
  amount: 0.01,
  memo: 'Example Pi Payment',
  metadata: { productId: 42, description: 'Demo purchase via Pi Network' }
};

export interface PiButtonProps {
  paymentData?: PaymentData;
  onConnected?: () => void;
  children?: React.ReactNode;
}

export function PiButton({ paymentData = defaultPaymentData, onConnected, children }: PiButtonProps) {
  const { connected } = usePiConnection();
  const purchase = usePiPurchase(paymentData);

  React.useEffect(() => {
    if (connected && onConnected) onConnected();
  }, [connected, onConnected]);

  return (
    <button disabled={!connected} onClick={purchase}>
      {children || 'Buy with Pi'}
    </button>
  );
}

Provide backend transaction support in your app

The local REST endpoints that you must provide are described in the Official Pi SDK Docs.

API Overview

Hooks

  • usePiConnection() — Handles Pi authentication, user connection, and exposes { connected, user, ready }. Use this to enable/disable purchase buttons, or to get the current Pi user.
  • usePiPurchase(paymentData) — Returns a purchase() callback that triggers the full Pi payment flow for the specified purchase (amount, memo, and metadata).

Parent SDK – pi-sdk-js

  • All Pi Network protocol types (e.g., PaymentData, PiUser) come from pi-sdk-js.
  • For low-level protocol customization (e.g., non-React environments), use pi-sdk-js directly.

Key Details

  • Peer dependency: React must be installed by the consuming app (peerDependency).
  • Browser only: Expects window.Pi to be present (via Pi Network browser SDK script tag).
  • No global bundle: Must be imported as an ES module.
  • No extra context provider required — hooks are self-contained and require no wrapper.
  • Colocated tests, idiomatic React patterns.

FAQ

Where is the main Pi SDK logic?

  • The low-level Pi JS SDK is provided by pi-sdk-js, which is a dependency. Do not use window.Pi directly in React—use these hooks/components for best results.

How do I mock/disable Pi for tests or development?

  • Stub or mock window.Pi in your test environment to return appropriate values. See Vitest or your test runner’s docs.

Can I use this with Next.js, Vite, CRA, etc?

  • Yes! It is ESM-first and framework-agnostic (but expects a React 18+ app as a peer).

📚 Further Resources

For more advanced use-cases, see the internal documentation or contact the Pi SDK team.