Better Native Alert Dialogs for React Native - @rn-nui/alert

Description:

@rn-nui/alert is a lightweight React Native UI library that delivers native-looking alert dialogs with consistent cross-platform behavior.

On Android, it properly implements Material 3 specifications with correct color tokens and layout patterns.

On iOS, it respects the system’s dark/light mode settings while maintaining Apple’s human interface guidelines.

You don’t have to write platform-specific code to get alerts that feel native to each OS.

Use Cases

Authentication flows where secure text input is required for passwords without compromising native UX.
Preference selection interfaces where users need to choose from multiple options with visual feedback.
Critical action confirmations that require proper destructive styling on iOS and position handling on Android.
Form validation where inline error messages aren’t sufficient and a dedicated prompt is needed.

Preview

Installation

1. Install and add the package to your project.

# Using npm
npm install @rn-nui/alert
# Using Yarn
yarn add @rn-nui/alert

2. Platform Setup

iOS

No extra steps are needed for iOS. It works out of the box.

Android

The library uses Material 3 components, so you must update your app’s theme.

Navigate to /android/app/src/main/res/values/styles.xml.
Change the parent of your AppTheme to a Material3 theme.

<resources>
    <!-- Base application theme. -->
    <style name="AppTheme" parent="Theme.Material3.DayNight.NoActionBar">
      <!-- Customize your theme here -->
    </style>
</resources>

If you want to add icons to your Android alerts, you’ll need to add the vector drawables to /android/app/src/main/res/drawable. You can then reference them by filename in the options. For instance, a file named ic_warning_24.xml would be used with { icon: 'ic_warning_24' }.

API and Usage

`Alert.alert()`

This displays a standard alert. It’s a direct upgrade to the built-in React Native version.

title (string): The main title text.
message (string, optional): The descriptive text below the title.
buttons (Array, optional): An array of button objects.
options (Object, optional): Extra options like cancelable (Android) or userInterfaceStyle (iOS).

// Alert with a destructive action
Alert.alert(
  'Delete Post',
  'Are you sure you want to permanently delete this post?',
  [
    { text: 'Cancel', style: 'cancel' },
    {
      text: 'Delete',
      style: 'destructive',
      onPress: () => console.log('Post deleted')
    },
  ]
);

`Alert.prompt()`

This shows a dialog with a text input field.

title (string): The prompt’s title.
message (string, optional): The prompt’s message.
buttons (Array, optional): An array of buttons. The onPress callback receives the input value.
type (string, optional): The input type. Can be 'plain-text', 'secure-text', or 'login-password'.
Other parameters include defaultValue (iOS), keyboardType (iOS), and options.

// Secure text prompt for a password
Alert.prompt(
  'Enter Password',
  'Your session has expired. Please log in again.',
  [
    { text: 'Cancel', style: 'cancel' },
    {
      text: 'Login',
      onPress: (password) => console.log('Password entered:', password),
    },
  ],
  'secure-text'
);

`Alert.items()`

Use this to display a list of tappable items.

title (string, optional): The dialog’s title.
items (Array, optional): An array of item objects, each with text, style, and onPress.
options (Object, optional): Options like message (iOS subtitle), cancelButtonText, and presentation (iOS: 'alert' or 'sheet').

// iOS action sheet
Alert.items(
  'Actions',
  [
    { text: 'Share Profile', onPress: () => {} },
    { text: 'Copy Link', onPress: () => {} },
    { text: 'Block User', style: 'destructive', onPress: () => {} },
  ],
  {
    message: 'Select an option',
    presentation: 'sheet',
  }
);

`Alert.singleChoice()` (Android Only)

This displays a list of options with radio buttons for single selection.

title (string): The dialog’s title.
buttons (Array): An array of choice objects, each with text, value, and defaultSelected.
options (Object, optional): Contains positive, negative, and neutral button handlers. The onPress for these buttons receives the selected value.

// Single choice for a setting
Alert.singleChoice(
  'Notification Tone',
  [
    { text: 'Default', value: 'default', defaultSelected: true },
    { text: 'Chime', value: 'chime' },
    { text: 'Silent', value: 'silent' },
  ],
  {
    positive: {
      text: 'OK',
      onPress: (selectedValue) => console.log('Selected tone:', selectedValue),
    },
  }
);

`Alert.multiChoice()` (Android Only)

This displays a list with checkboxes for multiple selections.

title (string): The dialog’s title.
items (Array): An array of choice objects, each with text, value, and defaultSelected.
options (Object, optional): Contains positive, negative, and neutral button handlers. The onPress receives an array of selected values.

// Multi-choice for selecting topics
Alert.multiChoice(
  'Follow Topics',
  [
    { text: 'Technology', value: 'tech', defaultSelected: true },
    { text: 'Science', value: 'sci' },
    { text: 'Art & Design', value: 'art', defaultSelected: true },
  ],
  {
    positive: {
      text: 'Save',
      onPress: (selectedValues) => console.log('Following:', selectedValues),
    },
    negative: { text: 'Cancel' }
  }
);

FAQs

Q: How is this different from the built-in React Native Alert API?
A: It’s a superset of the original. It adds more dialog types like prompt, items, singleChoice, and multiChoice. It also provides much deeper customization for Android to align with Material 3 design guidelines, including support for icons, header alignment, and distinct button positions.

Q: Why does my Android alert look wrong or crash my app?
A: The most common reason is failing to update the application theme. You must edit /android/app/src/main/res/values/styles.xml and set the parent attribute of your AppTheme to a Theme.Material3.* variant. The library depends on these themes for its components.