SuperToaster Documentation — AZ UI Kit

# Basic Usage

Add the toaster container once, then trigger toasts via data attributes or JavaScript.

1. Add Toaster Container

HTML (add once, typically in base template)

<div data-az-component="super-toaster"
     data-az-position="top-right"
     data-az-duration="5000">
</div>

2. Trigger Toasts

HTML

<!-- Via data attribute -->
<button data-az-toast
        data-az-toast-type="success"
        data-az-toast-message="Settings saved!">
  Save
</button>

<!-- With title -->
<button data-az-toast
        data-az-toast-type="info"
        data-az-toast-title="Heads up"
        data-az-toast-message="Your session expires in 5 minutes.">
  Show Info
</button>

# Toast Types

✓

success

Operation completed successfully

data-az-toast-type="success"

✕

error

Something went wrong

data-az-toast-type="error"

⚠

warning

Attention needed

data-az-toast-type="warning"

ℹ

info

Informational message

data-az-toast-type="info"

Loading Toast

JavaScript

// Show loading, then update
const toastId = SuperToaster.loading('Saving changes...');

await saveData();

SuperToaster.update(toastId, {
  type: 'success',
  message: 'Changes saved!'
});

# Positions

Position	Description
top-right	Top right corner (default)
top-left	Top left corner
top-center	Top center (banner-style)
bottom-right	Bottom right corner
bottom-left	Bottom left corner
bottom-center	Bottom center

HTML

<div data-az-component="super-toaster"
     data-az-position="bottom-center"
     data-az-offset="20">
</div>

# Toast Actions

Add clickable buttons inside toasts for user interaction.

JavaScript

SuperToaster.show({
  type: 'info',
  title: 'New message',
  message: 'You have 3 unread messages',
  actions: [
    {
      label: 'View',
      onClick: () => window.location.href = '/messages'
    },
    {
      label: 'Dismiss',
      variant: 'ghost'
    }
  ]
});

Undo Pattern

JavaScript

async function deleteItem(id) {
  const item = await removeItem(id);
  
  SuperToaster.show({
    type: 'success',
    message: 'Item deleted',
    duration: 8000,  // Longer duration for undo
    actions: [
      {
        label: 'Undo',
        onClick: async (toast) => {
          await restoreItem(item);
          SuperToaster.update(toast.id, {
            type: 'info',
            message: 'Item restored',
            actions: null
          });
        }
      }
    ]
  });
}

# HTMX Integration

SuperToaster automatically shows toasts from HTMX response headers.

Server-Triggered Toasts

Server Response Headers

HX-Trigger: az:toast

HX-Toast: {"type": "success", "message": "User created"}

Django Example

Python (Django)

from django.http import HttpResponse
import json

def create_user(request):
    # ... create user logic ...
    
    response = HttpResponse(status=201)
    response['HX-Toast'] = json.dumps({
        'type': 'success',
        'title': 'User Created',
        'message': f'Welcome, {user.name}!'
    })
    return response

FastAPI Example

Python (FastAPI)

from fastapi import Response
import json

@app.post("/users")
async def create_user(user: UserCreate, response: Response):
    new_user = await save_user(user)
    
    response.headers["HX-Toast"] = json.dumps({
        "type": "success",
        "message": "Account created successfully!"
    })
    
    return new_user

# Queuing & Limits

Control how multiple toasts are displayed.

HTML

<div data-az-component="super-toaster"
     data-az-position="top-right"
     data-az-max-visible="5"
     data-az-queue="true"
     data-az-stack-direction="down">
</div>

Attribute	Default	Description
data-az-max-visible	5	Max toasts shown at once
data-az-queue	true	Queue excess toasts vs. dismiss oldest
data-az-stack-direction	"up"	"up" \| "down" — new toasts stack
data-az-collapse	false	Group similar toasts with count badge

# JavaScript API

JavaScript

// Basic toast
SuperToaster.success('Saved!');
SuperToaster.error('Something went wrong');
SuperToaster.warning('Check your input');
SuperToaster.info('FYI...');

// Full options
SuperToaster.show({
  type: 'success',
  title: 'Order Confirmed',
  message: 'Your order #1234 has been placed.',
  duration: 8000,
  dismissible: true,
  icon: '🎉',  // Custom icon
  actions: [{ label: 'View Order', onClick: () => {} }]
});

// Loading toast (no auto-dismiss)
const id = SuperToaster.loading('Processing...');

// Update existing toast
SuperToaster.update(id, {
  type: 'success',
  message: 'Done!'
});

// Dismiss specific toast
SuperToaster.dismiss(id);

// Dismiss all
SuperToaster.dismissAll();

// Promise toast
SuperToaster.promise(
  fetch('/api/data'),
  {
    loading: 'Fetching data...',
    success: 'Data loaded!',
    error: 'Failed to load data'
  }
);

Full Options Reference

Option	Type	Description
type	string	"success" \| "error" \| "warning" \| "info" \| "loading"
title	string	Optional title/heading
message	string	Main toast content (required)
duration	number	Auto-dismiss time in ms (0 = persistent)
dismissible	boolean	Show close button (default: true)
icon	string	Custom icon (emoji or HTML)
actions	array	Array of {label, onClick, variant}
id	string	Custom ID (auto-generated if not set)

# Events

Event	Description	Detail
az:toast:show	Toast appeared	{ id, type, message }
az:toast:dismiss	Toast dismissed	{ id, reason }
az:toast:action	Action button clicked	{ id, action }
az:toast:update	Toast content updated	{ id, changes }