Skip to content

Toast Notifications

The Cartridge Controller SDK provides a built-in toast notification API that enables you to display contextual, user-friendly notifications directly within the controller interface. This API supports various notification types including transaction updates, achievements, network changes, and marketplace activities.

Overview

The toast API allows you to:

  • Display Transaction Status: Show transaction confirmation, pending, and error states
  • Network Switch Notifications: Notify users of network changes with visual indicators
  • Achievement Celebrations: Showcase earned achievements with XP amounts and visual flair
  • Quest Notifications: Display quest completion and claiming status
  • Marketplace Activities: Show purchase confirmations with item details
  • Error Handling: Display user-friendly error messages

Quick Start

import { toast } from "@cartridge/controller";
 
// Display a simple error message
toast({
  variant: "error",
  message: "Transaction failed",
});
 
// Show transaction confirmation
toast({
  variant: "transaction",
  status: "confirming",
  isExpanded: true,
});

API Reference

toast(options: ToastOptions)

The main toast function accepts a ToastOptions object with variant-specific properties.

import { toast } from "@cartridge/controller";
 
toast(options: ToastOptions);

Toast Variants

Error Toast

Display error messages with clear visual indicators.

toast({
  variant: "error",
  message: "Transaction failed",
});
Properties:
  • variant: "error" - Sets the toast type to error
  • message: string - The error message to display

Transaction Toast

Show transaction status updates with real-time progress indicators.

toast({
  variant: "transaction",
  status: "confirming",
  isExpanded: true,
});
Properties:
  • variant: "transaction" - Sets the toast type to transaction
  • status: string - Transaction status (e.g., "confirming", "confirmed", "failed")
  • isExpanded?: boolean - Whether to show expanded view with more details

Network Switch Toast

Notify users of network changes with network branding.

toast({
  variant: "network-switch",
  networkName: "Starknet Mainnet",
  networkIcon: "https://example.com/starknet-icon.png",
});
Properties:
  • variant: "network-switch" - Sets the toast type to network switch
  • networkName: string - Display name of the new network
  • networkIcon?: string - URL to the network's icon image

Achievement Toast

Celebrate user achievements with XP amounts and visual effects.

toast({
  variant: "achievement",
  title: "First Achievement!",
  subtitle: "Earned!",
  xpAmount: 50,
  isDraft: true,
});
Properties:
  • variant: "achievement" - Sets the toast type to achievement
  • title: string - Achievement title
  • subtitle?: string - Achievement subtitle or description
  • xpAmount?: number - XP amount earned (displays with special formatting)
  • isDraft?: boolean - Whether this is a draft/preview achievement

Quest Toast

Display quest completion and claiming notifications.

toast({
  variant: "quest",
  title: "First Quest!",
  subtitle: "Claimed!",
});
Properties:
  • variant: "quest" - Sets the toast type to quest
  • title: string - Quest title
  • subtitle?: string - Quest status or description

Marketplace Toast

Show marketplace purchase confirmations with item details.

toast({
  variant: "marketplace",
  action: "purchased",
  itemName: "Cool NFT #123",
  itemImage: "https://picsum.photos/seed/adventurer/200/200",
});
Properties:
  • variant: "marketplace" - Sets the toast type to marketplace
  • action: string - Action performed (e.g., "purchased", "listed", "sold")
  • itemName: string - Name of the item involved in the transaction
  • itemImage?: string - URL to the item's image

Usage Examples

Transaction Flow Integration

import { toast } from "@cartridge/controller";
 
async function handleTransaction() {
  try {
    // Show pending state
    toast({
      variant: "transaction",
      status: "pending",
      isExpanded: false,
    });
    
    const txHash = await executeTransaction();
    
    // Show confirming state
    toast({
      variant: "transaction",
      status: "confirming",
      isExpanded: true,
    });
    
    await waitForTransaction(txHash);
    
    // Show success (transaction toast automatically handles success)
    toast({
      variant: "transaction",
      status: "confirmed",
      isExpanded: false,
    });
    
  } catch (error) {
    // Show error
    toast({
      variant: "error",
      message: "Transaction failed: " + error.message,
    });
  }
}

Achievement System Integration

import { toast } from "@cartridge/controller";
 
function onAchievementEarned(achievement: Achievement) {
  toast({
    variant: "achievement",
    title: achievement.name,
    subtitle: "Achievement Unlocked!",
    xpAmount: achievement.xpReward,
    isDraft: false,
  });
}

Marketplace Purchase Flow

import { toast } from "@cartridge/controller";
 
async function handlePurchase(item: MarketplaceItem) {
  try {
    await purchaseItem(item);
    
    toast({
      variant: "marketplace",
      action: "purchased",
      itemName: item.name,
      itemImage: item.imageUrl,
    });
  } catch (error) {
    toast({
      variant: "error",
      message: "Purchase failed",
    });
  }
}

Demo Implementation

Here's a complete demo showing all toast variants with timing:

import { toast } from "@cartridge/controller";
 
function runToastDemo() {
  // Error toast
  toast({
    variant: "error",
    message: "Transaction failed",
  });
 
  // Transaction toast (1 second later)
  setTimeout(() => {
    toast({
      variant: "transaction",
      status: "confirming",
      isExpanded: true,
    });
  }, 1000);
 
  // Network switch toast (2 seconds later)
  setTimeout(() => {
    toast({
      variant: "network-switch",
      networkName: "Starknet Mainnet",
      networkIcon: "https://imagedelivery.net/0xPAQaDtnQhBs8IzYRIlNg/1b126320-367c-48ed-cf5a-ba7580e49600/logo",
    });
  }, 2000);
 
  // Achievement toast (3 seconds later)
  setTimeout(() => {
    toast({
      variant: "achievement",
      title: "First Achievement!",
      subtitle: "Earned!",
      xpAmount: 50,
      isDraft: true,
    });
  }, 3000);
 
  // Quest toast (4 seconds later)
  setTimeout(() => {
    toast({
      variant: "quest",
      title: "First Quest!",
      subtitle: "Claimed!",
    });
  }, 4000);
 
  // Marketplace toast (5 seconds later)
  setTimeout(() => {
    toast({
      variant: "marketplace",
      action: "purchased",
      itemName: "Cool NFT #123",
      itemImage: "https://picsum.photos/seed/adventurer/200/200",
    });
  }, 5000);
}

Best Practices

Timing and User Experience

  • Avoid Toast Spam: Don't display multiple toasts simultaneously that could overwhelm users
  • Appropriate Duration: Error messages should stay visible longer than success messages
  • Progressive Disclosure: Use isExpanded appropriately for transaction toasts

Visual Design

  • Consistent Branding: Use appropriate network icons and maintain visual consistency
  • Clear Messaging: Keep toast messages concise and actionable
  • Status Clarity: Ensure transaction status messages clearly indicate the current state

Integration Patterns

// Good: Clear, specific messages
toast({
  variant: "error",
  message: "Insufficient balance to complete transaction",
});
 
// Avoid: Vague error messages
toast({
  variant: "error", 
  message: "Something went wrong",
});
 
// Good: Meaningful achievement titles
toast({
  variant: "achievement",
  title: "Trading Expert",
  subtitle: "Complete 100 trades",
  xpAmount: 500,
});

Browser Support

The toast API is built into the Controller SDK and works across all browsers that support the Controller, including:

  • Chrome/Chromium browsers
  • Safari (desktop and mobile)
  • Firefox
  • Edge

Next Steps