Troubleshooting

Fix common Bridge UI setup issues—theme, provider, actions, and Tailwind.

Quick checks when something looks wrong after setup. Prefer the framework selector when comparing snippets.

Components render unstyled

Likely cause

Theme CSS not imported, or Tailwind is not scanning Bridge UI sources.

Import @bridge-ui/react/theme.css or @bridge-ui/vue/theme.css after @import "tailwindcss".
Keep that import in the stylesheet your bundler processes with Tailwind.

@import "tailwindcss";
@import "@bridge-ui/vue/theme.css";

@import "tailwindcss";
@import "@bridge-ui/react/theme.css";

Also confirm you are on Tailwind CSS v4. Bridge UI theme files use @theme and @source.

See Theme colors.

Theme colors still look teal / default

Tip

Remaps must use the same CSS variables ( --color-primary-*, …) in an @theme block that appears after the Bridge UI theme import. Partial remaps (only 500) leave hover/focus shades on the default scale.

Provider / context errors

Components and actions expect a provider higher in the tree.

Wrap the app (or layout) with BridgeUIProvider.
On Vue, you can also call createBridgeUI() when creating the app; still mount a provider where components / global should apply for that subtree.

See Installation.

Actions do nothing (open / snackbar / dialog)

Caution

Imperative APIs need hosts: render BridgeUIHosts inside BridgeUIProvider and pass the modal, dialog, and/or snackbar props required by the action you use.

See useModalAction, useDialogAction, useSnackbarAction.

Wrong framework package

Danger

Importing from @bridge-ui/react inside a Vue SFC (or the reverse) will fail at build or runtime. Match adapter to framework; see Dual apps.

TypeScript does not accept custom tokens

Register runtime tokens under provider tokens, then augment *Overrides (for example ButtonColorOverrides). Load framework augments.d.ts for typed provider classes.

See Tokens and Type overrides.

Icons missing or semantic names failing

Bridge UI does not ship icons. Install any icon library you prefer, then either:

Pass concrete icon components to props such as icon / startIcon, or
Register an icon adapter on global.icons so semantic names (and Bridge chrome) resolve

Missing adapter entries throw at resolve time—map every name in SEMANTIC_ICON_NAMES (or your augmented set).

Still stuck?

Open an issue on GitHub with framework, package versions, and a minimal reproduction. For contributing fixes, see Contributing.