🍞 Expo Toastee

Current Version: 2.0.4

A modern, elegant toast notification library for React Native Expo applications with Material You and Neobrutalist themes.

Features

• ✨ Beautiful, animated toast notifications with smooth enter/exit animations
• 🎨 Multiple toast types (success, error, info, warning)
• 🎭 Two stunning themes:
  • Material You: Modern Android 15 inspired pill-shaped toasts
  • Neobrutalist: Bold, vibrant design with sharp shadows
• 📏 6 responsive sizes (xs, sm, md, lg, xl, 2xl) with theme-specific configurations
• 🎨 Complete style customization - override any style property
• ⚡ Fast and lightweight - built with performance in mind
• 🔧 Full TypeScript support with comprehensive type definitions
• 📱 Cross-platform - works perfectly on iOS, Android, and Web
• 🎯 Flexible usage - works in React components AND standalone utility functions
• 🔀 Smart positioning (top/bottom) with safe area handling
• ⏱️ Configurable duration with auto-dismiss and manual control
• 👆 Interactive - tap to dismiss, smooth animations
• ⚙️ Dual configuration - via props or global settings
• 🛠️ Developer friendly - built with Bun for faster development

Installation

npm install expo-toastee
# or
yarn add expo-toastee
# or
bun add expo-toastee

Quick Start

1. Add ToastContainer to your root layout

Add the ToastContainer component to your app's root layout (usually App.tsx or your main layout file):

import React from 'react';
import { View } from 'react-native';
import { ToastContainer } from 'expo-toastee';

export default function App() {
  return (
    <View style={{ flex: 1 }}>
      {/* Your app content */}
      
      {/* Add ToastContainer at the root level */}
      <ToastContainer />
    </View>
  );
}

Configure via Props

You can also configure the toast behavior directly through ToastContainer props:

<ToastContainer 
  theme="neobrutalist"
  size="lg"
  defaultDuration={4000}
  defaultPosition="bottom"
  customStyles={{
    container: { borderRadius: 20 },
    text: { fontSize: 16 }
  }}
/>

2. Use toast functions anywhere

import { toast } from 'expo-toastee';

// In a React component
const MyComponent = () => {
  const handleSuccess = () => {
    toast.success('Operation completed successfully!');
  };

  return (
    <TouchableOpacity onPress={handleSuccess}>
      <Text>Show Success Toast</Text>
    </TouchableOpacity>
  );
};

// In a utility function (non-React)
export const showToast = (msg: string) => {
  toast.success(msg, { duration: 5000 });
};

// In an async function
const saveData = async () => {
  try {
    await api.saveData();
    toast.success('Data saved successfully!');
  } catch (error) {
    toast.error('Failed to save data');
  }
};

API Reference

Toast Functions

toast.success(message, options?)

Shows a success toast with a green background.

toast.error(message, options?)

Shows an error toast with a red background.

toast.info(message, options?)

Shows an info toast with a blue background.

toast.warning(message, options?)

Shows a warning toast with an orange background.

toast.clear()

Clears all currently visible toasts.

toast.remove(id)

Removes a specific toast by its ID.

Options

interface ToastOptions {
  duration?: number;              // Duration in milliseconds (default: 3000)
  position?: 'top' | 'bottom';    // Position on screen (default: 'top')
  animationType?: 'fade' | 'slide'; // Animation type (default: 'slide')
  theme?: 'material' | 'neobrutalist'; // Theme selection
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'; // Size selection (default: 'md')
  customStyles?: ToastCustomStyles; // Custom style overrides
}

Examples

// Basic usage
toast.success('Hello World!');

// With custom duration
toast.error('Something went wrong!', { duration: 5000 });

// Bottom positioned toast
toast.info('Check your network connection', { 
  position: 'bottom', 
  duration: 4000 
});

// No auto-dismiss (duration: 0)
toast.warning('This will stay until manually dismissed', { duration: 0 });

Theming & Customization

Built-in Themes

Expo Toastee comes with two carefully crafted themes:

Material You Theme (Default)

Inspired by Android 15's Material You design:

• Pill-shaped containers with generous rounded corners
• Soft, tinted backgrounds with subtle borders
• Dark text on light backgrounds for better accessibility
• Diffuse shadows for elegant depth
• Responsive sizing that adapts beautifully across all sizes

Neobrutalist Theme

Modern take on brutalist design:

• Bold borders with sharp contrast
• Vibrant colors that pop off the screen
• Hard drop shadows for dramatic effect
• Strong typography with confident letterforms
• Geometric precision in every element

Global Theme Configuration

There are two ways to configure toast defaults:

Method 1: Via ToastContainer Props (Recommended)

<ToastContainer 
  theme="neobrutalist"
  defaultDuration={4000}
  defaultPosition="bottom"
/>

Method 2: Via configureToasts Function

import { configureToasts } from 'expo-toastee';

// Set global theme
configureToasts({
  theme: 'neobrutalist',
  defaultDuration: 4000,
  defaultPosition: 'bottom',
});

// Now all toasts will use neobrutalist theme by default
toast.success('This uses neobrutalist theme!');

Per-Toast Configuration

Override theme, size, and other options for individual toasts:

// Use neobrutalist theme with large size
toast.success('Bold message!', { 
  theme: 'neobrutalist', 
  size: 'lg' 
});

// Small error toast
toast.error('Gentle error', { 
  theme: 'material', 
  size: 'sm' 
});

// Extra large info toast
toast.info('Important announcement!', { 
  size: '2xl',
  duration: 6000 
});

Custom Styles

Completely customize the appearance:

toast.success('Custom styled!', {
  customStyles: {
    container: {
      backgroundColor: 'transparent',
      borderWidth: 2,
      borderColor: '#FF6B6B',
    },
    successContainer: {
      backgroundColor: '#FF6B6B',
    },
    successText: {
      color: '#FFFFFF',
      fontWeight: 'bold',
      fontSize: 18,
    },
  },
});

Global Custom Styles

Set default custom styles for all toasts:

configureToasts({
  customStyles: {
    container: {
      borderRadius: 20,
    },
    text: {
      fontSize: 16,
      fontFamily: 'MyCustomFont',
    },
  },
});

Size System

Expo Toastee includes 6 responsive sizes to fit different use cases:

Size	Width	Max Width	Font Size	Use Case
xs	120px	180px	12px	Compact notifications
sm	160px	240px	14px	Small alerts
md	200px	300px	16px	Default size
lg	250px	400px	18px	Important messages
xl	320px	500px	20px	Prominent notifications
2xl	400px	600px	22px	Major announcements

// Different sizes
toast.success('Compact', { size: 'xs' });
toast.info('Default size'); // md is default
toast.error('Large error', { size: 'lg' });
toast.warning('Major alert!', { size: '2xl' });

TypeScript Support

Expo Toastee is written in TypeScript and provides full type definitions:

import { 
  toast, 
  ToastOptions, 
  ToastType, 
  ToastTheme,
  ToastCustomStyles,
  configureToasts 
} from 'expo-toastee';

const showCustomToast = (message: string, type: ToastType, options?: ToastOptions) => {
  switch (type) {
    case 'success':
      toast.success(message, options);
      break;
    case 'error':
      toast.error(message, options);
      break;
    // ... etc
  }
};

// Type-safe theme configuration
const themeConfig: ToastGlobalConfig = {
  theme: 'neobrutalist',
  defaultDuration: 5000,
  customStyles: {
    container: { borderRadius: 20 },
    text: { fontWeight: 'bold' },
  },
};

configureToasts(themeConfig);

ToastContainer Props

The ToastContainer component accepts all the same options as the global configuration:

interface ToastContainerProps {
  theme?: 'material' | 'neobrutalist';
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
  defaultDuration?: number;
  defaultPosition?: 'top' | 'bottom';
  defaultAnimationType?: 'fade' | 'slide';
  customStyles?: ToastCustomStyles;
}

// Example usage
<ToastContainer 
  theme="neobrutalist"
  size="lg"
  defaultDuration={5000}
  defaultPosition="bottom"
  customStyles={{
    container: { borderRadius: 12 },
    text: { fontWeight: 'bold' }
  }}
/>

Advanced Usage

Custom Toast Manager

For advanced use cases, you can access the underlying toast manager:

import { toastManager } from 'expo-toastee';

// Subscribe to toast updates
const unsubscribe = toastManager.subscribe((toasts) => {
  console.log('Current toasts:', toasts);
});

// Don't forget to unsubscribe
unsubscribe();

Performance

Expo Toastee is built with performance in mind:

• Minimal bundle size - Only includes what you use
• Optimized animations - Uses native driver for 60fps animations
• Memory efficient - Automatic cleanup of timers and subscriptions
• Fast development - Built with Bun for lightning-fast builds
• Cross-platform shadows - Custom shadow implementation for consistent look

Compatibility

Platform	Support	Notes
iOS	✅ Full	Native shadows, smooth animations
Android	✅ Full	Custom shadow implementation
Web	✅ Full	Responsive design, touch/mouse support

Requirements:

• React Native 0.64+
• Expo SDK 47+
• React 17+

Automated Publishing

This package uses GitHub Actions for automated CI/CD:

🔄 Workflow Features:

• Continuous Integration: Runs on every PR and push to main
• Automated Testing: Type checking and build verification
• Smart Publishing: Only publishes when version number changes
• Bun Integration: Fast builds and dependency management

🚀 Publishing Process:

1. Push to main with updated version in package.json
2. GitHub Actions automatically:
   • Installs dependencies with Bun
   • Runs type checking
   • Builds the package
   • Compares versions with npm registry
   • Publishes if version changed

⚙️ Setup Requirements:

To enable automated publishing, add NPM_TOKEN to your GitHub repository secrets:

1. Go to your repo → Settings → Secrets and variables → Actions
2. Add NPM_TOKEN with your npm access token

Roadmap

• Icon support for toast types
• Sound notifications (optional)
• Gesture dismissal (swipe to dismiss)
• Queue management for multiple toasts
• Custom animation presets
• Theme builder/generator
• Accessibility improvements (screen reader support)

Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please read our Contributing Guidelines for more details.

License

MIT License - see the LICENSE file for details.

Support

• 📝 Documentation: Full API reference and examples
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📧 Email: support@expo-toastee.dev

---

Made with ❤️ for the React Native Expo community

If you find this package helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting features
• 📖 Improving documentation
• 🤝 Contributing code