React UI components

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

Install the package

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:

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

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:

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

.checkout-theme {
  --dyn-color-ink: #101828;
  --dyn-size-widget-max-width: 420px;
}

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.

Connect wallet widget

Let users choose and connect an external wallet.

Flow payment widget

Run a complete Flow payment from a flow ID.

Text keys

Every piece of text you can replace, with its default.

React hooks

The hooks the components are built on.

Building UI guides

Build any screen yourself with the SDK.

​What the package includes

​Prerequisites

​Install the package

​Import the stylesheet

​Wrap your app in DynamicUiProvider

​Change the text

​Change the styles

​Related