# Native dialogs

> Use chrovia.ui to show native alerts, confirmations, and non-modal notifications. Learn the API methods, required entitlement, and browser-window requirements.

Source: https://console.getchrovia.com/en/docs/sdk-native-dialog

**Entitlement:** `nativeDialog`. **API:** `chrovia.ui`. No EP section is required. Use a Provision Service Worker; page use additionally requires `unrestrictedApi`.

## Show a dialog

Invoke this from your plugin's command handler while a browser window is available:

```js
async function askToContinue() {
  const ui = globalThis.chrovia?.ui;
  if (!ui) {
    throw new Error('nativeDialog is required');
  }
  const accepted = await ui.confirm('SDK Example', 'Continue with this operation?');
  if (!accepted) {
    return false;
  }
  await ui.alert('SDK Example', 'The operation was confirmed.');
  return true;
}
```

## Methods and behavior

| Method | Result |
| --- | --- |
| `alert(title, message)` | Promise resolving to `undefined` when the dialog completes |
| `confirm(title, message)` | Promise resolving to `true` on accept, `false` otherwise |
| `notify(title, message)` | Shows a non-modal notification; resolves to `undefined` when acknowledged or dismissed, not immediately on display |

Title and message are strings, not HTML. Alerts and confirmations use Chromium native message-box UI associated with a browser window. Notifications are non-modal; they do not return the user's approval. There are no custom button, checkbox, or HTML options in this interface.

## Handle failures

Await or catch Promises in event handlers; a call can reject if the dialog service is unavailable. With no suitable browser window, `alert()` can resolve without displaying anything and `confirm()` resolves to `false`. Provision Service Worker calls use the last active normal browser window. Do not depend on an alert being seen during headless or pre-window startup phases. For a request decision, keep [network interception's timeout and fail-open behavior](https://console.getchrovia.com/en/docs/sdk-network-intercept) in mind: leaving a confirmation open past the request timeout does not keep the request blocked.

This API is separate from `window.alert` and extension notifications. If `chrovia.ui` is missing, verify `nativeDialog` and the execution context. Test alerts, accepted and cancelled confirmations, and notification behavior independently.