Icons

Plug an icon library into Bridge UI with the icon adapter.

Bridge UI does not ship a default icon set. Components that need icons—and the Icon component itself—accept either a concrete icon component or a semantic name resolved through an optional icon adapter on BridgeUIProvider (global.icons).

Bridge only defines the IconAdapter interface — implement it as a plain object with resolve (and optional normalize).

Import

import { SEMANTIC_ICON_NAMES, type IconAdapter } from "@bridge-ui/vue";

import { SEMANTIC_ICON_NAMES, type IconAdapter } from "@bridge-ui/react";

Examples

Pass an IconAdapter to global.icons. On Vue you can also use createBridgeUI(); in Astro, wire it once via appEntrypoint.

Copy-paste adapters live in the core repo under packages/{react,vue}/examples/ (not published on npm). Each exports a create*IconAdapter() factory that returns a plain IconAdapter. Use SEMANTIC_ICON_NAMES for the full name list at runtime; extend via TypeScript module augmentation (SemanticIconNameOverrides)—see Type overrides.

Concrete components from any icon library still work without an adapter:

<Icon icon={AnyIconComponent} />

import type { IconAdapter, SemanticIconName } from "@bridge-ui/react";

const map = {
  /* …every SemanticIconName… */
} satisfies Record<SemanticIconName, unknown>;

const icons: IconAdapter = {
  resolve(name) {
    return map[name];
  },
};

File	Library
icon-lucide.ts	Lucide
icon-heroicons.ts	Heroicons (24 outline)
icon-tabler.ts	Tabler Icons
icon-phosphor.ts	Phosphor Icons
icon-fontawesome.ts	Font Awesome 6 (free solid)

File	Library
icon-lucide.ts	Lucide
icon-heroicons.ts	Heroicons (24 outline)
icon-tabler.ts	Tabler Icons
icon-phosphor.ts	Phosphor Icons
icon-fontawesome.ts	Font Awesome 6 (free solid)

Some libraries (for example Font Awesome) pass native definitions instead of components. Those adapters provide normalize so both semantic names and raw definitions render.

API

Export / option	Type	Description
IconAdapter.resolve	(name: SemanticIconName) => unknown	Maps a semantic name to an icon component (or native value).
IconAdapter.normalize	(source: unknown) => unknown	Optional transform for library-native values (e.g. Font Awesome).
SEMANTIC_ICON_NAMES	readonly SemanticIconName[]	Built-in semantic name list.
global.icons	IconAdapter	Provider option that enables semantic names app-wide.

Tip

Missing entries in the map throw at resolve time. Map every name in SEMANTIC_ICON_NAMES (or your augmented set) before shipping.

Next steps

Icon — component API and sizing
i18n — translate Bridge chrome strings
Default props — other global provider options