React Hook

The React hook integration is the recommended approach for most applications. It lets you open the depositOS widget as a full-screen modal overlay from anywhere in your component tree using a simple function call.

This approach uses two pieces: a DepositOSDepositProvider that wraps your app, and a useDepositOS() hook that gives any child component the ability to open, close, and inspect the widget.

Provider Setup

Wrap your application (or the relevant subtree) with DepositOSDepositProvider. Pass your deposit configuration and an optional onSuccess callback.

import { DepositOSDepositProvider } from "@gizmolab/depositos";

const depositConfig = {
  apiKey: "dos_live_…",
  destChain: 42161,
  destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  destAddress: "0xYourTreasuryAddress",
  enableWallet: true,
  enablePrivateMode: true,
};

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <DepositOSDepositProvider
      config={depositConfig}
      onSuccess={(txHash) => {
        console.log("Deposit successful:", txHash);
      }}
    >
      {children}
    </DepositOSDepositProvider>
  );
}

Provider Props

| Prop | Type | Required | Description | |---|---|---|---| | config | DepositOSConfig | Yes | Base widget configuration | | onSuccess | (txHash?: string) => void | No | Called when a deposit completes successfully | | children | ReactNode | Yes | Your application components |

The provider renders the widget inside a fixed, full-screen modal overlay with a blurred backdrop. When the widget is closed, it is unmounted entirely — no hidden iframes or background processes.

Using the Hook

In any component nested under the provider, call useDepositOS() to access the widget controls.

import { useDepositOS } from "@gizmolab/depositos";

function DepositButton() {
  const { openDepositOS, closeDepositOS, isOpen } = useDepositOS();

  return (
    <button
      onClick={() => openDepositOS()}
      disabled={isOpen}
    >
      {isOpen ? "Depositing..." : "Deposit Funds"}
    </button>
  );
}

Hook Return Value

| Property | Type | Description | |---|---|---| | openDepositOS | (overrides?: Partial<DepositOSConfig>) => void | Opens the widget modal. Accepts optional config overrides. | | closeDepositOS | () => void | Programmatically closes the widget modal. | | isOpen | boolean | Whether the widget modal is currently visible. |

Config Overrides

When calling openDepositOS(), you can pass a partial config object to override the base configuration provided to the provider. This is useful when you need different settings depending on context — for example, opening the widget with a specific default mode or a different order reference.

function PrivateDepositButton() {
  const { openDepositOS } = useDepositOS();

  return (
    <button
      onClick={() =>
        openDepositOS({
          defaultMode: "private",
          orderRef: "order-12345",
        })
      }
    >
      Private Deposit
    </button>
  );
}

Overrides are shallow-merged with the base config. When the widget closes, overrides are cleared and the next openDepositOS() call starts fresh from the base config.

Full Example

Here is a complete example showing the provider, a navigation bar with a deposit button, and a page component that opens the widget with context-specific overrides.

// app/providers.tsx
import { DepositOSDepositProvider } from "@gizmolab/depositos";

const config = {
  apiKey: "dos_live_…",
  destChain: 42161,
  destToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  destAddress: "0xYourTreasuryAddress",
  enableWallet: true,
  enablePrivateMode: true,
};

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <DepositOSDepositProvider
      config={config}
      onSuccess={(txHash) => {
        // Post to your backend, show a toast, redirect, etc.
        fetch("/api/deposits", {
          method: "POST",
          body: JSON.stringify({ txHash }),
        });
      }}
    >
      {children}
    </DepositOSDepositProvider>
  );
}

// app/components/Navbar.tsx
import { useDepositOS } from "@gizmolab/depositos";

export function Navbar() {
  const { openDepositOS } = useDepositOS();

  return (
    <nav>
      <h1>My App</h1>
      <button onClick={() => openDepositOS()}>
        Add Funds
      </button>
    </nav>
  );
}

// app/checkout/page.tsx
import { useDepositOS } from "@gizmolab/depositos";

export default function CheckoutPage({ orderId }: { orderId: string }) {
  const { openDepositOS } = useDepositOS();

  return (
    <div>
      <h2>Complete Your Purchase</h2>
      <button
        onClick={() =>
          openDepositOS({ orderRef: orderId })
        }
      >
        Pay with Crypto
      </button>
    </div>
  );
}

When to Use the Hook vs. the Component

| Scenario | Recommended Approach | |---|---| | Open as a modal overlay from a button | React Hook | | Embed inline in a specific page section | React Component | | Need to open from multiple places in the app | React Hook | | Building a dedicated deposit page | React Component | | Non-React application | Iframe or Script Tag |

The hook approach is generally preferred because it avoids layout concerns — the modal overlay handles positioning automatically.