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

# React UI components

> Install @dynamic-labs-sdk/react-ui to add prebuilt wallet connection and Flow payment widgets to a React web app, and adjust their text and styles.

`@dynamic-labs-sdk/react-ui` is a library of prebuilt React components that run on top of the JavaScript SDK and its React hooks. It gives you complete screens for connecting an external wallet and for paying a [Flow payment](https://www.dynamic.xyz/docs/flow/payments.md), so you can add those experiences without building every screen yourself. The rest of the SDK stays headless, and you can still build any screen from the [Building UI guides](https://www.dynamic.xyz/docs/javascript/building-ui/overview.md) instead.

The package is for React web apps. It renders DOM elements and depends on `react-dom`, so it does not work in React Native.

## What the package includes

The package has two entry points. Import from the one that matches what you are building.

| Entry point | Use it for |
| - | - |
| `@dynamic-labs-sdk/react-ui` | The [connect wallet widget](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/connect-wallet-widget.md), the wallet lists it is built from, `DynamicUiProvider`, and general building blocks such as `Button` and `QRCode` |
| `@dynamic-labs-sdk/react-ui/flow` | The [Flow payment widget](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/flow-widget.md) and the single-method payment widgets |

The widgets are the main components. Each one runs a complete task, calls the SDK for you, and reports the result through a callback:

| Widget | Entry point | What it does |
| - | - | - |
| `ConnectWalletOptionWidget` | Main | Lets the user choose a wallet and connect it, including chain choice and QR pairing |
| `FlowWidget` | Flow | Runs a whole Flow payment: the payer chooses a wallet, an exchange, or a deposit address |
| `FlowPayWithWalletWidget` | Flow | Runs a Flow payment from a connected wallet only |
| `FlowPayWithExchangeWidget` | Flow | Runs a Flow payment through an exchange only |
| `FlowDepositAddressWidget` | Flow | Runs a Flow payment to a deposit address only |

The main entry point also exports the views the connect wallet widget is built from (`WalletList`, `WalletChainList`, `ProviderList`, and `WalletAccountBalances`, which lists a wallet account's token balances), plus smaller components such as `Badge`, `Button`, `Checkbox`, `CopyField`, `Panel`, `QRCode`, `SearchBar`, `Select`, and `TokenMark`. Use them when you want the same look in screens you build yourself.

## Prerequisites

* A React web app set up with `@dynamic-labs-sdk/client` and `@dynamic-labs-sdk/react-hooks`, as described in the [React quickstart](https://www.dynamic.xyz/docs/javascript/reference/react-quickstart.md). The components read SDK state through the hooks, so they must render inside `QueryClientProvider` and `DynamicProvider`.
* A chain extension for each chain whose wallets you want to show, as described in [Adding extensions](https://www.dynamic.xyz/docs/javascript/reference/adding-extensions.md).

## Install the package

```bash theme={"system"}
npm install @dynamic-labs-sdk/react-ui
```

Install it at the same version as your other `@dynamic-labs-sdk` packages. The SDK checks the versions at startup and throws a `VersionMismatchError` when they differ. The package supports React 18 and 19.

## Import the stylesheet

Import one stylesheet once, at the root of your app. The stylesheets are plain CSS, so your bundler needs no extra configuration.

| Stylesheet | Import it when |
| - | - |
| `@dynamic-labs-sdk/react-ui/index.css` | You use only components from the main entry point |
| `@dynamic-labs-sdk/react-ui/flow.css` | You use any Flow widget. It already includes everything in `index.css` |

## Wrap your app in DynamicUiProvider

`DynamicUiProvider` renders a wrapper element with the `dyn-root` class and sets up the animation and text context the components need. A component rendered outside it has no styles. Mount it once, inside `DynamicProvider`:

```tsx theme={"system"}
import "@dynamic-labs-sdk/react-ui/index.css";

import { DynamicUiProvider } from "@dynamic-labs-sdk/react-ui";
import { DynamicProvider } from "@dynamic-labs-sdk/react-hooks";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";

import { App } from "./App";
import { dynamicClient } from "./dynamicClient";

const queryClient = new QueryClient();

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <QueryClientProvider client={queryClient}>
      <DynamicProvider client={dynamicClient}>
        <DynamicUiProvider>
          <App />
        </DynamicUiProvider>
      </DynamicProvider>
    </QueryClientProvider>
  </StrictMode>
);
```

`dynamicClient` is the client your app creates at startup, as in the [React quickstart](https://www.dynamic.xyz/docs/javascript/reference/react-quickstart.md).

For the Flow widgets, import `flow.css` instead of `index.css` and add the `dyn-flow-root` class to the provider, because the Flow styles apply only inside an element that has it:

```tsx theme={"system"}
import "@dynamic-labs-sdk/react-ui/flow.css";

import { DynamicUiProvider } from "@dynamic-labs-sdk/react-ui";

<DynamicUiProvider className="dyn-flow-root">
  <App />
</DynamicUiProvider>;
```

## Change the text

Every widget ships with English default text. Pass a `text` dictionary to `DynamicUiProvider` to replace any of it. The dictionary is keyed by the component's slot name, then by the text key:

```tsx theme={"system"}
import { DynamicUiProvider } from "@dynamic-labs-sdk/react-ui";

<DynamicUiProvider
  text={{
    "dyn-connect-wallet-option-widget": {
      listTitle: "Choose your wallet",
      connectingStatusMessage: "Open {wallet} and approve the request.",
    },
  }}
>
  <App />
</DynamicUiProvider>
```

Some keys accept a `{wallet}` placeholder, which the widget replaces with the wallet's display name. A slot or key that the component does not read is a TypeScript error, so a typo cannot fall back silently to the default text. [Text keys](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/text-reference.md) lists every slot and key with its default. You can also wrap part of the tree in `TextProvider` to change the text in one place only. Nested dictionaries merge, and the innermost value wins.

## Change the styles

The components are styled to work without changes, and you can adjust them with ordinary CSS:

* **Design tokens.** Colors, type, spacing, and sizes are CSS custom properties named `--dyn-*`, declared on `.dyn-root` rather than on `:root`, so they never leak into the rest of your page. Override one on the provider's class to change it everywhere, such as `--dyn-color-ink` for text color or `--dyn-size-widget-max-width` for the widget width.
* **Your rules win.** The package puts all of its rules in CSS cascade layers named `dyn` and `dyn-flow`. Any rule you write outside a layer takes precedence over them, so you never need `!important`.
* **Stable selectors.** Each element carries a `data-slot` attribute, such as `data-slot="dyn-connect-wallet-option-widget"`. Target these attributes rather than generated class names.
* **Your own classes.** Every widget accepts a `className` for its root element, and `DynamicUiProvider` adds its `className` after `dyn-root`.

```css theme={"system"}
.checkout-theme {
  --dyn-color-ink: #101828;
  --dyn-size-widget-max-width: 420px;
}
```

```tsx theme={"system"}
import { DynamicUiProvider } from "@dynamic-labs-sdk/react-ui";

<DynamicUiProvider className="checkout-theme">
  <App />
</DynamicUiProvider>
```

The components ship with a light theme only. There is no dark theme yet, so override the color tokens if your app needs one.

## Related

> [card] [Connect wallet widget](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/connect-wallet-widget.md)
>
> Let users choose and connect an external wallet.

> [card] [Flow payment widget](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/flow-widget.md)
>
> Run a complete Flow payment from a flow ID.

> [card] [Text keys](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/text-reference.md)
>
> Every piece of text you can replace, with its default.

> [card] [React hooks](https://www.dynamic.xyz/docs/javascript/reference/react-hooks-guide.md)
>
> The hooks the components are built on.

> [card] [Building UI guides](https://www.dynamic.xyz/docs/javascript/building-ui/overview.md)
>
> Build any screen yourself with the SDK.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.