> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trustware.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Control the widget open state with a ref

> Use a TrustwareWidgetRef to open or close the deposit flow programmatically, and configure initial step, theme, and visibility callbacks.

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](/integration/drop-in-widget) is simpler to set up.

## Setup

<Steps>
  <Step title="Import the ref type">
    ```tsx theme={null}
    import { useRef } from "react";
    import {
      TrustwareProvider,
      TrustwareWidget,
      type TrustwareWidgetRef,
    } from "@trustware/sdk";
    ```
  </Step>

  <Step title="Create the ref">
    ```tsx theme={null}
    const widgetRef = useRef<TrustwareWidgetRef>(null);
    ```
  </Step>

  <Step title="Pass the ref and configure the widget">
    ```tsx theme={null}
    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>
      );
    }
    ```
  </Step>
</Steps>

## Widget props

| 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. |

```tsx theme={null}
// 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;
```

<Note>
  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.
</Note>

## 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.

```tsx theme={null}
<TrustwareWidget
  ref={widgetRef}
  initialStep="select-token"
  defaultOpen={true}
/>
```

<Tip>
  Combine `defaultOpen={true}` with `initialStep` to open the widget immediately at the right step when the page loads.
</Tip>