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

# Add React UI components with shadcn

> Copy the source of the React UI components into your app with the shadcn CLI from Dynamic's registry, so you own and can edit every component.

The React UI components are also published as a [shadcn](https://ui.shadcn.com) 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](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/overview.md#change-the-styles) 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](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).
* 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](https://ui.shadcn.com/docs/installation). 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:

```bash theme={"system"}
npm install @dynamic-labs-sdk/client @dynamic-labs-sdk/react-hooks @tanstack/react-query
```

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

```json components.json theme={"system"}
{
  "registries": {
    "@dynamic-ui": "https://dynamic-static-assets.com/react-ui/v1/{name}.json"
  }
}
```

The shadcn documentation explains [namespaced registries](https://ui.shadcn.com/docs/registry/namespace) and the other [`components.json` fields](https://ui.shadcn.com/docs/components-json).

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:

```bash theme={"system"}
npx shadcn search @dynamic-ui
```

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

```bash theme={"system"}
npx shadcn add @dynamic-ui/dyn-dynamic-ui-provider @dynamic-ui/dyn-flow-widget
```

The [shadcn CLI reference](https://ui.shadcn.com/docs/cli) 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`.

> [!NOTE]
>
> 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:

```tsx theme={"system"}
import "@/components/dynamic-ui/flow/widgets/FlowWidget/FlowWidget.entry.css";
```

The stylesheets are plain CSS that use cascade layers, so your bundler needs no extra configuration. [Change the styles](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/overview.md#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:

```tsx theme={"system"}
import "@/components/dynamic-ui/flow/widgets/FlowWidget/FlowWidget.entry.css";

import { DynamicUiProvider } from "@/components/dynamic-ui/components/DynamicUiProvider";
import { FlowWidget } from "@/components/dynamic-ui/flow/widgets/FlowWidget";

export const Checkout = ({ flowId }: { flowId: string }) => (
  <DynamicUiProvider className="dyn-flow-root">
    <FlowWidget
      flowId={flowId}
      onPaymentCompleted={(flow) => console.log("Paid", flow.id)}
      onPaymentFailed={(flow) => console.log("Not paid", flow.id)}
    />
  </DynamicUiProvider>
);
```

`Checkout` must render inside `QueryClientProvider` and `DynamicProvider`, as in the [React quickstart](https://www.dynamic.xyz/docs/javascript/reference/react-quickstart.md). 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](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/flow-widget.md) and [Connect wallet widget](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/connect-wallet-widget.md) 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.

## Related

> [card] [React UI components](https://www.dynamic.xyz/docs/javascript/building-ui/react-ui/overview.md)
>
> Install the components as a package instead.

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


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