nativedocs

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 banner

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 menu of choices

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.

PropertyTypeDescription
titlestringPicker title.
descriptionstringSupporting text under the title.
modestringdate, time, or datetime. Prefer this over the older type alias.
minstringEarliest value, in the selected mode's ISO shape.
maxstringLatest value, in the selected mode's ISO shape.
initialstringInitially selected value, in the selected mode's ISO shape.
localestringBCP-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. Android paints the bar with the color you pass; iOS keeps the system background and picks the readable content style for it.

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

Register handlers with bdk.on(event, listener), which returns an unsubscribe function.

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