Alert

Display native alerts consistently across all platforms using a single, unified API.

Installation

npm install @native-ui-org/primitives

pnpm add @native-ui-org/primitives

yarn add @native-ui-org/primitives

bun add @native-ui-org/primitives

Overview

The Alert system includes two main parts:

Feature	Description	Platforms
`showAlert()`	Promise-based helper for simple alerts	iOS, Android, Web
`AlertDialog`	Accessible alert component for full UI control	iOS, Android, Web

Setup & Usage Guide

The Alert primitive adapts automatically to the platform. Setup is minimal and the same code works everywhere.

1. Install and Import

Install from npm:

npm install @native-ui-org/primitives

Then import from the package:

import { showAlert } from "@native-ui-org/primitives";

2. Basic Setup

No special setup is required for mobile. On web, wrap your app with the AlertDialogProvider to enable global alert management.

import { AlertDialogProvider } from "@native-ui-org/primitives";

export default function App() {
  return (
    <AlertDialogProvider>
      <YourApp />
    </AlertDialogProvider>
  );
}

The provider is safe on mobile and ensures that web alerts render properly.

3. Using showAlert

Once setup, you can call showAlert() anywhere in your code — same API, same behavior, all platforms.

const result = await showAlert({
  title: "Delete file?",
  message: "This action cannot be undone.",
  buttons: [
    { text: "Cancel", value: "cancel", style: "cancel" },
    { text: "Delete", value: "delete", style: "destructive" },
  ],
});

if (result === "delete") {
  // Handle destructive action
}

4. Custom AlertDialog

If you need full control, use the AlertDialog components directly. They work across all platforms.

import {
  AlertDialog,
  AlertDialogOverlay,
  AlertDialogContent,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogCancel,
  AlertDialogAction,
} from "@native-ui-org/primitives";

function CustomAlert() {
  const [open, setOpen] = React.useState(false);

  return (
    <AlertDialog open={open} onOpenChange={setOpen}>
      <AlertDialogOverlay>
        <AlertDialogContent>
          <AlertDialogTitle>Custom Alert</AlertDialogTitle>
          <AlertDialogDescription>
            This is a custom styled alert dialog.
          </AlertDialogDescription>

          <AlertDialogCancel>Cancel</AlertDialogCancel>
          <AlertDialogAction>Confirm</AlertDialogAction>
        </AlertDialogContent>
      </AlertDialogOverlay>
    </AlertDialog>
  );
}

API Reference

showAlert(options)

Promise-based alert helper.

function showAlert<Value = string>(
  options: ShowAlertOptions<Value>
): Promise<Value | undefined>

Option	Type	Default	Description
`title`	string	—	Alert title
`message`	string	—	Description text
`buttons`	`AlertButton[]`	`[{ text: "OK" }]`	Alert actions
`cancelable`	boolean	`true`	Whether it can be dismissed

AlertButton:

Property	Type	Description
`text`	string	Button label
`value`	any	Returned value when pressed
`style`	`"default" \| "cancel" \| "destructive"`	Visual hint
`autoFocus`	boolean	Focus this button (web only)

Platform Behavior

Platform	Implementation	Characteristics
iOS / Android	Uses native `Alert.alert()` internally	Native look and behavior
Web	Renders through `AlertDialog`	Accessible, customizable, non-blocking
Others (Desktop, Hybrid)	Uses the same unified API	Consistent alerts everywhere

Accessibility

Web:

role="alertdialog"
aria-modal="true"
Focus trapping and restoration
Escape key dismiss (if cancelable)

Mobile:

Uses native accessibility APIs automatically

Version History

Version	Notes
`0.1.0`	Initial release — unified `showAlert()` and `AlertDialog`.

Summary: Use showAlert() for quick, cross-platform alerts. Use AlertDialog for full UI control when you need customization. Both share the same foundation and deliver consistent, accessible behavior everywhere.