@clempixels/react-native-aura-alert

A highly customizable, lightweight, theme-driven global alert and toast orchestration suite for React Native and Expo applications. Built using TypeScript and designed to blend natively into your application's design system.

Features

• 🔄 Dual Operational Modes: Supports modal confirmation sheets and auto-dismissing toast notifications using a single unified trigger.
• 🎨 Dynamic Theme Engine: Overrides surface, background, primary actions, text overlays, and accents directly through your root provider layout.
• ⚡ Zero-Hook Imperative Execution: Invoke overlays flawlessly from nested utilities, business logic files, or API interceptors without needing custom React Hooks.
• 🚀 Ultra-lightweight & Tree-shakable: Pre-bundled using tsup with separate ESM and CommonJS exports.

Installation

Install the package into your React Native or Expo workspace:

npm install @clempixels/react-native-aura-alert

Getting Started

1. Wrap Your Application Root

In order to register the static listener engine, wrap your main application tree with the AuraAlertProvider. This is also where you configure your active color palette tokens.

// App.tsx
import React from 'react';
import { AuraAlertProvider } from '@clempixels/react-native-aura-alert';
import MainScreen from './src/MainScreen';

const APP_THEME = {
  background: '#0B0B0C',
  surface: '#1A1A1E',
  text: '#FFFFFF',
  textMuted: '#9E9E9E',
  primary: '#7C3AED', // Premium purple accent
  danger: '#EF4444',
  overlay: 'rgba(0, 0, 0, 0.75)',
};

export default function App() {
  return (
    <AuraAlertProvider theme={APP_THEME}>
      <MainScreen />
    </AuraAlertProvider>
  );
}

Usage Syntax

Because AuraAlert exposes a static event listener interface, you can import it and fire actions from any file inside your repository—no component injection or hooks required.

1. Triggering a Confirmation Modal

Ideal for disruptive actions, user choices, or security steps.

import { AuraAlert } from '@clempixels/react-native-aura-alert';

const handleAccountDeletion = () => {
  AuraAlert.show({
    mode: 'modal',
    title: 'Delete Account',
    message: 'Are you sure you want to permanently erase your profile data? This process cannot be undone.',
    confirmText: 'Erase Profile',
    cancelText: 'Cancel',
    onConfirm: () => {
      // Execute deletion sequence
      console.log('Account removed');
    },
    onCancel: () => console.log('Action aborted'),
  });
};

2. Triggering an Auto-Dismissing Toast

Perfect for background changes, action confirmations, or quick success/error readouts.

import { AuraAlert } from '@clempixels/react-native-aura-alert';

const saveUserSettings = () => {
  // Logic to process update saves
  
  AuraAlert.show({
    mode: 'toast',
    message: 'Profile configuration synced successfully! ✨',
    duration: 2500, // Optional: defaults to 3000ms
  });
};

API Reference

AuraAlert.show(options)

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | mode | 'modal' | 'toast' | 'modal' | Layout profile style targeting either an overlay modal or a snackbar notification. | | message | string | Required | The primary instructional string or textual content of the prompt. | | title | string | undefined | Header string centered above the message string (Modal specific layout). | | confirmText | string | 'OK' | Label text string bound to the primary operational action. | | cancelText | string | 'Cancel' | Label text string bound to the abort/dismissal option. | | onConfirm | () => void | undefined | Function trigger executed upon clicking the positive selection button. | | onCancel | () => void | undefined | Function trigger executed upon clicking the cancellation button. | | duration | number | 3000 | Length of time (in milliseconds) the view remains active before auto-closing (Toast specific). |

AlertTheme Configuration Interface

type AlertTheme = {
  background?: string; // Container structure context
  surface?: string;    // Base sheet color
  text?: string;       // Header title & prominent text strings
  textMuted?: string;  // Supporting content or secondary tags
  primary?: string;    // Active click/confirmation elements
  danger?: string;     // Destruction warning highlights
  overlay?: string;    // Background shroud alpha channel
};

License

MIT © Clement