react-native-dream-toast/README.md

A customizable, theme-ready toast system for React Native with queueing, safe-area support, swipe to dismiss, and modal compatibility.

# 🌸 react-native-dream-toast
## React Native Smart Toast / React Native Dream Toast

A beautiful, customizable, and lightweight toast notification system for React Native. Supports theming, queueing, global config, icons, and full TypeScript support.

---


## ✨ Features

- 🔔 Minimal toast system for Android & iOS
- ⏳ Auto-dismiss with custom duration
- 🔃 Queueing support (FIFO)
- 🎨 Theming with multiple preset styles
- ⚙️ Global config with `setToastConfig()`
- 🧩 Custom renderers
- 📦 Written in TypeScript

---


<!-- Image Preview -->
![Toast Demo](./src/assets/demo-layout.gif)

---


## ⚠️ Peer Dependencies

Make sure the following packages are installed in your project:

```bash
npm install react-native-safe-area-context
# or
yarn add react-native-safe-area-context
```

## 📦 Installation

```bash
npm install react-native-dream-toast
# or
yarn add react-native-dream-toast
```
---

## 🚀 Quick Start

### 1. Wrap your app with the `ToastProvider`

```tsx
import { ToastProvider } from 'react-native-dream-toast';

export default function App() {
  return (
    <ToastProvider>
      <YourApp />
    </ToastProvider>
  );
}
```
### 2. Show a toast anywhere

```tsx
import { Toast } from 'react-native-dream-toast';

Toast.show({
  message: 'Hello from Dream Toast!',
  type: 'success',
});
```
---

### 🛠 Global Config: `setToastConfig()`

You can globally configure default toast styles, behavior, and position:

```ts
import { setToastConfig } from 'react-native-dream-toast';

setToastConfig({
  queue: true,
  topOffset: 40,
  bottomOffset: 40,
  toastStyle: {
    success: { backgroundColor: '#1b5e20' },
    error: { backgroundColor: '#b71c1c' },
    warning: { backgroundColor: '#f57f17' },
    info: { backgroundColor: '#01579b' },
  },
  textStyle: {
    success: { color: '#fff', fontWeight: 'bold' },
    error: { color: '#fff' },
    warning: { color: '#000' },
    info: { color: '#fff', fontStyle: 'italic' },
  },
});
```
## 💡 Usage Examples

### Basic Toast

```tsx
Toast.show({
  message: 'This is an info toast!',
  type: 'info',
  autoClose: true,
  duration: 3000,
});
```

### Custom callback

```tsx
Toast.show({
  message: 'This will log on close',
  type: 'error',
  onClose: () => console.log('Toast closed!'),
});
```

### Add Custom Icons for Visual Feedback

```tsx
Toast.show({
  message: 'Success!',
  icon: require('./assets/success.png'), // or JSX
});
```


## 🔧 Props

| Prop         | Type                                                      | Default       | Description                            |
|--------------|-----------------------------------------------------------|---------------|----------------------------------------|
| `message`    | `string`                                                  | –             | The toast message to display           |
| `type`       | `'success' \| 'error' \| 'info' \| 'warning' \| 'default'`| `'default'`   | Type of toast                          |
| `icon`       | `ReactNode \| number`                                     | –             | Optional icon (image or JSX)           |
| `position`   | `'top' \| 'bottom'`                                       | `'top'`       | Toast position                          |
| `autoClose`  | `boolean`                                                 | `true`        | Auto-dismiss toast                     |
| `duration`   | `number`                                                  | `3000`        | Auto-close delay in milliseconds       |
| `onClose`    | `() => void`                                              | –             | Callback when toast is dismissed       |
| `toastStyle` | `ViewStyle`                                               | –             | Override toast container style         |
| `textStyle`  | `TextStyle`                                               | –             | Override text style                    |
| `styleName`  | `'beautyToast' \| 'elegantToast' \| ...`                 | `'beautyToast'`| Style preset group                     |
| `queue`      | `boolean`                                                 | `true`        | Queue or override toasts               |


## 🎨 Available Preset Toast Styles

`react-native-dream-toast` includes several pre-configured style themes for a quick start:

- `default`
- `beautyToast`
- `paperToast`
- `vintageToast`

<!-- Image Preview -->
![Toast Style Demo](./src/assets/sample_layout.png)


## 🔌 Custom Renderer (Override or Add Any Type)

You can override the UI of any existing toast type (like `'success'`, `'error'`, `'info'`, etc.) or define your own custom toast types using the `renderers` option in `Toast.configure()`:

```tsx
import { Toast } from 'react-native-dream-toast';

Toast.configure({
  renderers: {
    // 🔁 Override built-in "success" toast
    success: ({ message, onClose }) => (
      <Pressable
        onPress={onClose}
        style={{ backgroundColor: '#388e3c', padding: 12, borderRadius: 10 }}
      >
        <Text style={{ color: 'white', fontWeight: 'bold' }}>{message}</Text>
      </Pressable>
    ),

    // 🔁 Override built-in "error" toast
    error: ({ message, onClose }) => (
      <Pressable
        onPress={onClose}
        style={{ backgroundColor: '#d32f2f', padding: 12, borderRadius: 10 }}
      >
        <Text style={{ color: '#fff' }}>{message}</Text>
      </Pressable>
    ),

    // ✨ Define a new toast type "fancy"
    fancy: ({ message, onClose }) => (
      <Pressable
        onPress={onClose}
        style={{
          backgroundColor: '#6a1b9a',
          padding: 16,
          borderRadius: 16,
          borderWidth: 2,
          borderColor: '#ab47bc',
        }}
      >
        <Text style={{ color: '#fff', fontSize: 18 }}>💎 {message}</Text>
      </Pressable>
    ),
  },
});
```
### Usage Example

```tsx
Toast.show({ type: 'success', message: 'Success with custom UI!' });
Toast.show({ type: 'fancy', message: 'This is a fancy toast 🎉' });
```
✅ You can customize or completely replace the UI for any toast type, and even introduce your own new types with their own appearance and behavior.
## 📚 TypeScript Support

All exports are fully typed:

```ts
import { ToastProps, setToastConfig } from 'react-native-dream-toast';
```
---


## 🧠 Best Practices

### 1. Use `queue: true` for Sequential Toasts

If you're triggering multiple toasts in quick succession, enable the queue system:

```ts
setToastConfig({ queue: true });
```

### 2. Wrap Your App in `<SafeAreaProvider>`

To ensure proper positioning of toasts (especially on devices with notches or insets), wrap your root component like this:

```tsx
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';

export default function App() {
  return (
    <SafeAreaProvider>
      <SafeAreaView style={{ flex: 1 }}>
        {/* your navigation or app content */}
      </SafeAreaView>
    </SafeAreaProvider>
  );
}
```
This ensures toasts correctly calculate top/bottom offsets using the device’s safe area insets.

--- 


## 🧑 Author

Made with ❤️ by **Antos Maman**

- [GitHub](https://github.com/antosmamanktr)
- [LinkedIn](https://www.linkedin.com/in/antosmaman/)
- For issues and contributions, feel free to open a [GitHub issue](https://github.com/your-github-username/react-native-letter-flatlist/issues)

## 📄 License

[MIT](./LICENSE) Copyright (c) 2025 Antos Maman

---