Skip to main content
By default, TrustwareWidget manages its own open/closed state. When your app needs to trigger the deposit flow from elsewhere (a button in a nav bar, a checkout step, a game event), you can take control of that state using a ref.

​
When to use this pattern

Choose this pattern when:
  • your app needs to open or close the deposit flow from outside the widget
  • you want to set the initial step the user lands on
  • you need lifecycle callbacks for when the widget opens or closes
If you do not need programmatic control, the drop-in widget is simpler to set up.

​
Setup

1

Import the ref type

import { useRef } from "react";
import {
  TrustwareProvider,
  TrustwareWidget,
  type TrustwareWidgetRef,
} from "@trustware/sdk";
2

Create the ref

const widgetRef = useRef<TrustwareWidgetRef>(null);
3

Pass the ref and configure the widget

export function ControlledWidget() {
  const widgetRef = useRef<TrustwareWidgetRef>(null);

  return (
    <TrustwareProvider config={trustwareConfig}>
      <button onClick={() => widgetRef.current?.open()}>
        Open deposit
      </button>
      <TrustwareWidget
        ref={widgetRef}
        defaultOpen={false}
        initialStep="home"
        showThemeToggle={false}
        onOpen={() => console.log("opened")}
        onClose={() => console.log("closed")}
      />
    </TrustwareProvider>
  );
}

​
Widget props

PropTypeDescription
theme"light" | "dark" | "system"Sets the widget color scheme. Defaults to "system".
initialStep"home" | "select-token" | "crypto-pay" | "processing" | "success" | "error"The step the widget opens on. Defaults to "home".
defaultOpenbooleanWhether the widget renders open on first mount.
onOpen() => voidCallback fired when the widget opens.
onClose() => voidCallback fired when the widget closes.
showThemeTogglebooleanWhether to show the theme toggle control inside the widget.

​
Using the ref

TrustwareWidgetRef exposes three methods:
MethodDescription
open()Open the widget.
close()Close the widget. Shows a confirmation dialog first if a transaction is in progress.
isOpen()Returns true when the widget is currently open. Useful for syncing your own UI state.
// Open the widget from a button
<button onClick={() => widgetRef.current?.open()}>
  Deposit
</button>

// Close from a parent component
<button onClick={() => widgetRef.current?.close()}>
  Cancel
</button>

// Reflect open state in your own UI
const open = widgetRef.current?.isOpen() ?? false;
The ?. optional chaining guard is important: ref.current is null until the widget mounts. Using widgetRef.current?.open() prevents a runtime error if the button is clicked before the widget renders.

​
Starting on a specific step

Use initialStep to land the user at a particular point in the flow rather than the home screen. This is useful when you already know the context: for example, if the user has already selected a token elsewhere in your UI. 
<TrustwareWidget
  ref={widgetRef}
  initialStep="select-token"
  defaultOpen={true}
/>
Combine defaultOpen={true} with initialStep to open the widget immediately at the right step when the page loads.