Skip to main content
The React UI components are also published as a shadcn registry. Instead of installing @dynamic-labs-sdk/react-ui as a package, you run the shadcn CLI, which copies the source of each component you add into your app. You then own that code and can change it like any other file in your project. Use this approach when you want to edit the markup or styles beyond what the design tokens and text dictionary allow. If you do not need to edit the components, installing the package is simpler, and you receive fixes when you upgrade.

Prerequisites

  • A React web app set up with @dynamic-labs-sdk/client, @dynamic-labs-sdk/react-hooks, and @tanstack/react-query, 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.
  • A components.json file at the root of your project. Run npx shadcn init to create one if your project does not have it yet, as described in the shadcn installation guide. The components do not use Tailwind CSS, so the Tailwind settings in that file do not affect them.

Install the SDK packages first

Install the Dynamic SDK packages before you add any component:
The components import @dynamic-labs-sdk/client and @dynamic-labs-sdk/react-hooks, but the registry lists them without a version. When the shadcn CLI finds them already installed, it keeps your versions, so the components run against the same SDK version as the rest of your app. If they are missing, the CLI installs the latest release, which may not match the other @dynamic-labs-sdk packages in your app. The SDK checks the versions at startup and throws a VersionMismatchError when they differ.

Point shadcn at the Dynamic registry

The components are not listed in the shadcn directory, so you tell the CLI where to find them. Add the @dynamic-ui namespace to the registries field of your components.json:
components.json
The shadcn documentation explains namespaced registries and the other components.json fields. The v1 segment of the URL is the major version of the components. It must match the major version of the @dynamic-labs-sdk packages you installed, because each major version of the registry is built against the same major version of the SDK. When you upgrade the SDK to a new major version, change this segment to match it, such as v2 for version 2.x. The registry also publishes its full catalog at https://dynamic-static-assets.com/react-ui/v1/registry.json. To list the available components from the command line, run:

Add a component

Add a component by its name in the @dynamic-ui namespace. Add dyn-dynamic-ui-provider the first time, because every component needs DynamicUiProvider to render with styles:
The shadcn CLI reference lists every option of add and the other commands. The CLI also adds every component the one you named is built from, and installs the packages they use, such as motion. Generic component names start with dyn-, such as dyn-connect-wallet-option-widget, and Flow component names start with dyn-flow-, such as dyn-flow-widget.
If you use pnpm, recent versions can stop an install with ERR_PNPM_IGNORED_BUILDS when a new dependency has a build script you have not approved, and the CLI then exits before it copies any files. Run pnpm approve-builds to approve or deny the listed packages, then run the add command again.
Everything lands in a dynamic-ui directory inside your components alias, such as src/components/dynamic-ui/, so it never mixes with your own components. The files keep the layout they have in the package, for example components/dynamic-ui/flow/widgets/FlowWidget/.

Import the stylesheet

Each component ships a <Component>.entry.css file next to its source. It imports the design tokens and the styles of that component and of every component it is built from. Import the entry stylesheet of each top-level component you render once, at the root of your app:
The stylesheets are plain CSS that use cascade layers, so your bundler needs no extra configuration. Change the styles explains the tokens, layers, and selectors, which work the same way as in the package.

Render the component

Import the components from the files the CLI added. This example renders the Flow payment widget, so it adds the dyn-flow-root class to DynamicUiProvider, because the Flow styles apply only inside an element that has it:
Checkout must render inside QueryClientProvider and DynamicProvider, as in the React quickstart. The @/ prefix is the path alias from your components.json. The components themselves import each other with relative paths, so they work with any alias. The props, callbacks, and text keys are the same as in the package. Flow payment widget and Connect wallet widget describe them.

Update the components

Because the source lives in your project, upgrading the SDK packages does not change the components. To pick up a newer version, run the same add command again. The CLI asks before it replaces each file that already exists, so you can keep the files you changed. To compare a file with the registry version first, run the command with --dry-run --diff followed by the file path.

React UI components

Install the components as a package instead.

Flow payment widget

Run a complete Flow payment from a flow ID.
Last modified on November 19, 2026