Control the widget open state with a ref

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

Import the ref type

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

Create the ref

const widgetRef = useRef<TrustwareWidgetRef>(null);

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>
  );
}

Prop	Type	Description
`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"`.
`defaultOpen`	`boolean`	Whether the widget renders open on first mount.
`onOpen`	`() => void`	Callback fired when the widget opens.
`onClose`	`() => void`	Callback fired when the widget closes.
`showThemeToggle`	`boolean`	Whether to show the theme toggle control inside the widget.

Using the ref

TrustwareWidgetRef exposes three methods:

Method	Description
`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.

Get Started

Integration

Configuration

Events & Errors

Guides

SDK Reference

Control the widget open state with a ref

When to use this pattern

Setup

Widget props

Using the ref

Starting on a specific step

​When to use this pattern

​Setup

​Widget props

​Using the ref

​Starting on a specific step

When to use this pattern

Setup

Widget props

Using the ref

Starting on a specific step