@tetrax/jetray

A premium, animatable, and positionable notification component for React and Next.js applications featuring iOS-style 3D notification stacking.

Designed with rich dark aesthetics, custom icons, and auto-dismiss/stack-discard behaviors powered by framer-motion and react-icons/io.

Features

• 🎨 Elegant Dark Aesthetic: Modern rounded pill layout matching premium design systems.
• 📱 iOS-Style Stacking: Stack multiple active notifications on top of each other. Older notifications scale down, fade, and shift back like stacked cards.
• 🕒 Auto-Dismiss Timers: Configure auto-dismiss durations for active toasts.
• 🧹 Automatic Stacking Discard: Background toasts automatically clean themselves up after 2 seconds to prevent backlog pile-up.
• 📍 Multi-Position Layout: Easy screen positioning including top-left, top-center, top-right, bottom-left, bottom-center, bottom-right, left (vertical center), right (vertical center), and static.
• ⚡ Next.js Ready: Pre-compiled with "use client" directives for seamless Next.js App Router compatibility.

Installation

Install @tetrax/jetray:

npm install @tetrax/jetray

Quick Start

1. Basic Inline Notification

Render a simple, static inline notification:

import { Jetray } from '@tetrax/jetray';

export default function SimpleDemo() {
  return (
    <Jetray 
      type="success"
      message="File Uploaded Successfully" 
      onClose={() => console.log('Closed')}
    />
  );
}

2. Screen-Positioned Notification

Render a notification fixed at the top-center of the screen:

import { Jetray } from '@tetrax/jetray';

export default function PositionedDemo() {
  return (
    <Jetray 
      type="info"
      position="top-center"
      message="Connecting to voice channel..."
      duration={3000}
      onClose={() => console.log('Dismissed')}
    />
  );
}

Advanced: iOS-Style Stacking

To implement iOS-style stacked cards, render active notifications by calculating their stackIndex relative to other active notifications in the same position group. The newest notification has stackIndex={0}.

import React, { useState } from 'react';
import { Jetray } from '@tetrax/jetray';

export default function StackedDemo() {
  const [notifications, setNotifications] = useState([]);

  const addNotification = (type, message, position = 'bottom-right') => {
    setNotifications((prev) => [...prev, { id: Date.now(), type, message, position }]);
  };

  const removeNotification = (id) => {
    setNotifications((prev) => prev.filter((t) => t.id !== id));
  };

  return (
    <div>
      <button onClick={() => addNotification('success', 'Operation succeeded!')}>
        Trigger Notification
      </button>

      {notifications.map((notification, index) => {
        // Calculate stackIndex: count how many notifications triggered after this one share the same position
        const notificationsAfter = notifications.slice(index + 1);
        const stackIndex = notificationsAfter.filter(t => t.position === notification.position).length;

        return (
          <Jetray
            key={notification.id}
            position={notification.position}
            type={notification.type}
            message={notification.message}
            stackIndex={stackIndex}
            duration={4000} // Active notification dismisses in 4s
            onClose={() => removeNotification(notification.id)}
          />
        );
      })}
    </div>
  );
}

API Reference

Props

| Prop | Type | Default | Description | | :--- | :--- | :--- | :--- | | message | string | undefined | The text content of the notification. | | children | React.ReactNode | undefined | Alternative way to supply message/content. | | type | 'success' \| 'error' \| 'warning' \| 'info' | 'success' | Select pre-configured themes (green success, red error, yellow warning, blue info). | | icon | React.ReactNode | (preset) | Override the default state icon. Pass null or false to hide the icon. | | stackIndex | number | 0 | Stack position depth. 0 represents the front/active notification. Backwards offsets (>0) will scale, fade, and shift back automatically. | | onClose | function | undefined | Triggered when the user clicks the close icon or when the auto-dismiss timer fires. | | duration | number | undefined | Time in milliseconds before the notification auto-dismisses (applies only to the active stackIndex = 0 notification). | | position | string | 'static' | Layout preset: 'top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right', 'left', 'right', or 'static'. | | className | string | "" | Additional CSS classes for custom container styling. |

License

MIT © Tetrax Inc.