React FlashMessages

Overview

React FlashMessages provides an accessible, fast, and tiny (approx. 3KB gzipped) API for showing contextual notifications in your React apps. It supports custom themes, multiple positions, queue management, and simple animations.

🚀 Quick Start

Wrap your application with the provider and use the hook to show messages.

import { FlashMessageProvider } from 'flashmessage-js'

export default function App({ Component, pageProps }) {
  return (
    <FlashMessageProvider>
      <Component {...pageProps} />
    </FlashMessageProvider>
  )
}

import { useFlashMessage } from 'flashmessage-js'

function MyComponent(){
  const { showFlashMessage } = useFlashMessage()
  return (
    <button 
      onClick={() => showFlashMessage('Saved!', 'success')}
    >
      Save
    </button>
  )
}

📖 API (brief)

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| defaultPosition | FlashMessagePosition | "top" | Initial position of messages |
| maxMessages | number | 5 | Maximum number of messages to display |
| defaultTheme | FlashMessageTheme | Default theme | Custom color theme |


## useFlashMessage Hook

const {
  showFlashMessage,    // Show a new message
  dismissFlashMessage, // Dismiss specific message by ID
  clearAllMessages,    // Clear all messages
  position,            // Current position
  setPosition,         // Change position dynamically
  theme,               // Current theme
  setTheme            // Change theme dynamically
} = useFlashMessage();


## showFlashMessage

showFlashMessage(
  message: string,
  type: "success" | "error" | "info" | "warning",
  options?: {
    duration?: number // milliseconds, default: 3000
  }
): string // Returns message ID



### Message Types

- success - Green success messages
- error - Red error messages
- info - Blue informational messages
- warning - Orange/yellow warning messages


### Positions

- top - Top center
- bottom - Bottom center
- top-left - Top left corner
- top-right - Top right corner
- bottom-left - Bottom left corner
- bottom-right - Bottom right corner


## 🎨 Custom Themes

import { useFlashMessage } from 'flashmessage-js';
import type { FlashMessageTheme } from 'flashmessage-js';

function MyComponent() {
  const { setTheme } = useFlashMessage();
  
  const customTheme: FlashMessageTheme = {
    success: {
      bg: "#00d9ff",
      dark: "#00b8d4",
      text: "#000000"
    },
    error: {
      bg: "#ff006e",
      dark: "#d90058",
      text: "#ffffff"
    },
    info: {
      bg: "#8338ec",
      dark: "#6930c3",
      text: "#ffffff"
    },
    warning: {
      bg: "#ffbe0b",
      dark: "#fb8500",
      text: "#000000"
    }
  };
  
  return (
    <button onClick={() => setTheme(customTheme)}>
      Apply Custom Theme
    </button>
  );
}
 

Examples

                                        
### Basic Usage

const { showFlashMessage } = useFlashMessage();

// Success message
showFlashMessage('Data saved successfully!', 'success');

// Error message
showFlashMessage('Failed to save data', 'error');

// Info message
showFlashMessage('New update available', 'info');

// Warning message
showFlashMessage('Your session will expire soon', 'warning');


### Custom Duration

// Show for 5 seconds
showFlashMessage('Long message', 'info', { duration: 5000 });

// Show indefinitely (manual dismiss only)
showFlashMessage('Manual dismiss', 'success', { duration: 0 });


### Form Validation

async function handleSubmit(e: React.FormEvent) {
  e.preventDefault();
  
  try {
    await saveData(formData);
    showFlashMessage('Form submitted successfully!', 'success');
  } catch (error) {
    showFlashMessage(error.message, 'error');
  }
}


### API Requests with Loading State

async function fetchData() {
  const id = showFlashMessage('Loading data...', 'info', { duration: 0 });
  
  try {
    const result = await api.getData();
    dismissFlashMessage(id);
    showFlashMessage('Data loaded successfully!', 'success');
  } catch (error) {
    dismissFlashMessage(id);
    showFlashMessage('Failed to load data', 'error');
  }
}

### Change Position Dynamically

const { setPosition, showFlashMessage } = useFlashMessage();

<button onClick={() => {
  setPosition('top-right');
  showFlashMessage('Messages now appear top-right', 'info');
}}>
  Move to Top Right
</button>
                                    

Contributing

Contributions are welcome — open a pull request or file an issue.

License

MIT © Adu Yeboah