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 "@thebdk/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. Pass ok_label and cancel_label to set the button labels. 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.",
  ok_label: "Delete",
  cancel_label: "Keep"
});

// 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({
  menudata: {
    sections: [
      {
        items: [
          { title: "Share", returned_data: "share" },
          { title: "Edit", returned_data: "edit" },
          { title: "Delete", returned_data: "delete" }
        ]
      }
    ]
  }
});

Prompt for an app-store rating

Show the OS rating prompt at a natural moment.

await bdk.ui.requestRating();

Pick a date or time

Open a native date/time picker. Subscribe to datePicked before you call — it still fires on every build.

On current app builds the awaited call also resolves the result directly ({ ok: true, value, epochMs }) and datePicked delivers the epoch milliseconds. On older builds the result arrives only on datePicked.

Property	Type	Description
`title`	`string`	Picker title.
`description`	`string`	Supporting text under the title.
`mode`	`string`	`date`, `time`, or `datetime`. Prefer this over the older `type` alias.
`min`	`string`	Earliest value, in the selected mode's ISO shape.
`max`	`string`	Latest value, in the selected mode's ISO shape.
`initial`	`string`	Initially selected value, in the selected mode's ISO shape.
`locale`	`string`	BCP-47 locale hint. iOS only; Android follows the device locale.

bdk.on("datePicked", (value) => {
  console.log("date chosen:", value); // epoch ms on current builds
});

const result = await bdk.ui.pickDateTime({
  title: "Select a date",
  mode: "date"
});

if (result.ok) {
  console.log(result.value, result.epochMs);
}

Style the status bar

Set the status-bar color with a six-digit #RRGGBB value (Android accepts upper- or lowercase hex). Appearance depends on the app’s configured status-bar mode and tint. For Translucent mode, current build generation and soft deploy write a default tint of 50% for light colors and 85% for dark ones unless an explicit tint is set. Apps built on native baselines iOS v2.30 / Android v2.32 or later apply the same adaptive default when the tint key is absent; apps on older baselines fall back to 50%.

For a saved preview in the BDK Preview app, configure its starting colour in BDK Native or on thebdk.com: open its card, choose Edit, set its status-bar colour (white by default), then Save. Pick that preview again in the BDK Preview launcher to refresh its cached colour, then close and relaunch the app. Colour is per preview; per-preview status-bar mode and tint are not yet available. BDK Preview itself has an explicit tint of 85%.

await bdk.ui.updateStatusBar({
  color: "#111111"
});

Control screen orientation

Set or lock the screen orientation. lockOrientation() locks the current orientation; pass { locked: false } to unlock.

Android only — wrap the call in try/catch.

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

// Android only — locks the current orientation
await bdk.ui.lockOrientation();

// Unlock
await bdk.ui.lockOrientation({ locked: false });

Disable the iOS back-swipe

Suppress the iOS left-edge back-swipe when a screen owns that gesture itself. disableLeftSwipe() disables it; pass { enabled: true } to re-enable.

iOS only — wrap the call in try/catch.

await bdk.ui.disableLeftSwipe();

// Re-enable
await bdk.ui.disableLeftSwipe({ enabled: 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.

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))
];

// 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());