vkui-bridge

@vkma.dev/vkui-bridge is React glue between @vkma.dev/bridge and @vkontakte/vkui. The provider streams the host’s theme, safe-area insets and adaptivity from bridge events into a ready ConfigProvider shell. Semantics copy @vkontakte/vk-bridge-react.

npm install @vkma.dev/vkui-bridge
# peers: @vkma.dev/bridge ^0.2.0, @vkontakte/vkui ^8.0.0, react ^18 | ^19

Use

main.tsx of a VK Mini App:

import bridge from "@vkma.dev/bridge";
import { VKBridgeConfigProvider } from "@vkma.dev/vkui-bridge";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App";
import "@vkontakte/vkui/dist/vkui.css";

// Tell the host the app is ready: folds the host preloader, enables history.
void bridge.send("VKWebAppInit");

createRoot(document.getElementById("root")!).render(
    <StrictMode>
        <VKBridgeConfigProvider>
            <App />
        </VKBridgeConfigProvider>
    </StrictMode>,
);

VKBridgeConfigProvider composes ConfigProvider → AdaptivityProvider → AppRoot(mode="full") with bridge-computed defaults:

ConfigProvider prop	Source
colorScheme	VKWebAppUpdateConfig plus a VKWebAppGetConfig bootstrap (useBridgeAppearance)
platform	"vkcom" when vk_platform === "desktop_web" in the launch params
isWebView	bridge.isWebView()
hasCustomPanelHeaderAfter	always true, reserving the PanelHeader corner for the host controls
AdaptivityProvider props	host adaptivity via transformVKBridgeAdaptivity(useBridgeAdaptivity())
AppRoot.safeAreaInsets	VKWebAppUpdateInsets and config insets via useBridgeInsets

Any prop the app passes explicitly wins over the computed value. The provider accepts the whole ConfigProvider prop surface and spreads it last.

Hooks

Every hook reads the default bridge instance.

• useBridgeAppearance() returns ColorSchemeType | undefined. Streams VKWebAppUpdateConfig and bootstraps with VKWebAppGetConfig. Outside a mini app it returns undefined — VKUI resolves the theme itself.
• useBridgeInsets() returns SafeAreaInsets | undefined. Reads VKWebAppUpdateInsets and the insets field of the config. A bottom beyond 150 becomes 0 — the virtual-keyboard clamp.
• useBridgeAdaptivity() returns { type, viewportWidth, viewportHeight }. type is the host verdict (adaptive, force_mobile, force_mobile_compact, or null) plus the viewport at the last change.

Links

• npm: @vkma.dev/vkui-bridge

Sections

• Hooks — the three hooks’ signatures and boundaries.
• Provider — VKBridgeConfigProvider and overrides.