Native UI

Show native banners, alerts, popups, menus, pickers, and control the status bar and orientation from your web code.

Set up

Use bdk.ui to drive native surfaces from your web code. Calls that return a value (menu taps, popup buttons, picks) deliver it on an event — subscribe with bdk.on(...) before you call.

Outside the app these calls don't run (triggered: false) and no native surface appears. Provide a web fallback for anything the user must respond to.

import { createBdkNative } from "@bdk/native/browser";

export const bdk = createBdkNative();

Show a non-blocking in-app banner for status messages like "You're offline."

await bdk.ui.showBanner({
  title: "You're offline",
  description: "Changes will sync when you reconnect."
});

Show an alert

Show a blocking system alert the user must acknowledge before continuing.

await bdk.ui.showAlert({
  title: "Upload failed",
  description: "Please try again."
});

Ask the user to confirm

Show a popup with action buttons. The pressed button arrives on the popupClosed event — subscribe first.

The popupClosed payload tells you which button dismissed the popup — the OK or Cancel button.

const off = bdk.on("popupClosed", (button) => {
  console.log("popup dismissed via", button);
});

await bdk.ui.showPopup({
  title: "Delete this item?",
  description: "This cannot be undone.",
  positive_button: "Delete",
  negative_button: "Cancel"
});

// later, when you no longer need it
off();

Show a list or action sheet. The tapped item arrives on the menuClicked event — subscribe first.

bdk.on("menuClicked", (item) => {
  console.log("menu item tapped:", item);
});

await bdk.ui.showMenu({
  options: ["Share", "Edit", "Delete"]
});

Prompt for an app-store rating

Show the OS rating prompt at a natural moment.

await bdk.ui.requestRating();

Pick a date or option

Open a native date/time picker or option list. Date/time picks arrive on datePicked; option picks arrive on optionPicked. Subscribe to the one your picker produces before you call.

bdk.on("datePicked", (value) => {
  console.log("date chosen:", value);
});

await bdk.ui.pickDateTime({
  mode: "date",
  min: "2026-01-01"
});

Style the status bar

Set the status-bar color and light/dark content.

await bdk.ui.updateStatusBar({
  style: "dark"
});

Control screen orientation

Set or lock the screen orientation.

lockOrientation is Android-only and is skipped on iOS.

await bdk.ui.setOrientation({ orientation: "landscape" });

// Android only — skipped on iOS
await bdk.ui.lockOrientation({ orientation: "portrait" });

Disable the iOS back-swipe

Suppress the iOS left-edge back-swipe when a screen owns that gesture itself.

iOS only. Skipped on Android.

await bdk.ui.disableLeftSwipe({ disable: true });

Event reference

menuClicked — the menu item the user tapped (its title and data).
popupClosed — which button dismissed the popup.
datePicked — the date/time the user selected.
optionPicked — the option the user chose.

A throwing listener surfaces once as a BdkError with code BDK_LISTENER_ERROR, via both the onError config callback and the error event.

const offs = [
  bdk.on("menuClicked", (item) => console.log("menu", item)),
  bdk.on("popupClosed", (button) => console.log("popup", button)),
  bdk.on("datePicked", (value) => console.log("date", value)),
  bdk.on("optionPicked", (value) => console.log("option", value))
];

// Surface listener errors centrally
const bdkWithErrors = createBdkNative({
  onError: (err) => console.error(err.code, err.message)
});

// Clean up when the screen unmounts
offs.forEach((off) => off());