@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 insideQueryClientProviderandDynamicProvider. - A chain extension for each chain whose wallets you want to show, as described in Adding extensions.
- A
components.jsonfile at the root of your project. Runnpx shadcn initto 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:@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
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:
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.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:
Render the component
Import the components from the files the CLI added. This example renders the Flow payment widget, so it adds thedyn-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 sameadd 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.
Related
React UI components
Install the components as a package instead.
Flow payment widget
Run a complete Flow payment from a flow ID.