Customization

Overview

Solid Toast provides extensive customization options through the ToastOptions interface. You can customize individual toasts or set global defaults via the Toaster component.

ToastOptions Interface

interface ToastOptions {
  id?: string;
  icon?: Renderable;
  duration?: number;
  ariaProps?: {
    role: 'status' | 'alert';
    'aria-live': 'assertive' | 'off' | 'polite';
  };
  className?: string;
  style?: JSX.CSSProperties;
  position?: ToastPosition;
  unmountDelay?: number;
  iconTheme?: IconTheme;
}

Styling Options

Custom Styles

Use the style prop to apply inline CSS styles:

Basic Styling
Dark Theme
Gradient Background

toast.success('Custom styled toast', {
  style: {
    background: '#10b981',
    color: 'white',
    padding: '16px',
    'border-radius': '8px',
  },
});

toast('Dark mode notification', {
  style: {
    background: '#1f2937',
    color: '#f9fafb',
    border: '1px solid #374151',
    'box-shadow': '0 4px 6px rgba(0, 0, 0, 0.3)',
  },
});

toast.success('Gradient toast', {
  style: {
    background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
    color: 'white',
    'font-weight': 'bold',
  },
});

style

JSX.CSSProperties

CSS properties to apply to the toast. Merged with default styles.

CSS Classes

Use the className prop for external styling:

toast('Classy notification', {
  className: 'my-custom-toast',
});

/* styles.css */
.my-custom-toast {
  background: #f0f9ff;
  border-left: 4px solid #0284c7;
  font-family: 'Inter', sans-serif;
}

className

string

CSS class name to apply to the toast element.

Both style and className can be used together. Inline styles take precedence.

Icon Customization

Custom Icons

Replace the default icon with your own:

String Icon
JSX Icon
No Icon

toast.success('Task completed', {
  icon: '🎉',
});

toast.error('Failed', {
  icon: '❌',
});

import { CheckCircle } from './icons';

toast('Custom icon', {
  icon: <CheckCircle size={24} color="#22c55e" />,
});

toast.success('Success without icon', {
  icon: null,
});

icon

Renderable

Custom icon to display. Can be a string (emoji), JSX element, or null to hide the icon.

type Renderable = JSX.Element | string | null

Icon Theme

Customize the colors of default icons:

toast.success('Custom icon colors', {
  iconTheme: {
    primary: '#10b981',
    secondary: '#ffffff',
  },
});

toast.error('Custom error colors', {
  iconTheme: {
    primary: '#ef4444',
    secondary: '#fef2f2',
  },
});

iconTheme

IconTheme

Customize default icon colors.

interface IconTheme {
  primary?: string;   // Main icon color
  secondary?: string; // Background/accent color
}

Icon Theme Example

// Global icon theme via Toaster
<Toaster
  toastOptions={{
    iconTheme: {
      primary: '#6366f1',
      secondary: '#e0e7ff',
    },
  }}
/>

// Per-toast override
toast.loading('Processing...', {
  iconTheme: {
    primary: '#f59e0b',
    secondary: '#fef3c7',
  },
});

Duration

Control how long toasts remain visible:

Fixed Duration
Persistent
Default Durations

// Short duration (1 second)
toast('Quick message', { duration: 1000 });

// Long duration (10 seconds)
toast.error('Important error', { duration: 10000 });

// Never auto-dismiss
toast('Must dismiss manually', { duration: Infinity });

// Dismiss programmatically later
const id = toast('Persistent', { duration: Infinity });
setTimeout(() => toast.dismiss(id), 5000);

// Uses type-specific defaults:
toast.success('2 seconds'); // 2000ms
toast.error('4 seconds');   // 4000ms
toast.loading('Infinity');  // Infinity
toast('4 seconds');         // 4000ms

duration

number

default:"3000"

Time in milliseconds before the toast auto-dismisses. Use Infinity to prevent auto-dismiss.Type-specific defaults:

blank: 4000ms
success: 2000ms
error: 4000ms
loading: Infinity
custom: 4000ms

Loading toasts default to Infinity duration. Always dismiss or update them when operations complete.

Position

Control where individual toasts appear:

toast('Top right', { position: 'top-right' });
toast('Bottom center', { position: 'bottom-center' });
toast('Top left', { position: 'top-left' });

position

ToastPosition

default:"'top-right'"

Position of the toast on screen.

type ToastPosition = 
  | 'top-left' 
  | 'top-center' 
  | 'top-right' 
  | 'bottom-left' 
  | 'bottom-center' 
  | 'bottom-right'

Set a default position via <Toaster position="..."> and override per toast as needed.

Unmount Delay

Control the exit animation duration:

// Fast exit (200ms)
toast('Quick exit', { unmountDelay: 200 });

// Slow exit (1 second)
toast('Slow exit', { unmountDelay: 1000 });

// No animation
toast('Instant removal', { unmountDelay: 0 });

unmountDelay

number

default:"500"

Time in milliseconds to wait before removing the toast from the DOM after dismissal. Used for exit animations.

The default unmount delay is 500ms, which allows for smooth exit animations.

Accessibility

ARIA Properties

Customize accessibility attributes:

Status Role
Alert Role
Off

// Polite, non-intrusive announcement
toast('Background update complete', {
  ariaProps: {
    role: 'status',
    'aria-live': 'polite',
  },
});

// Urgent, immediate announcement
toast.error('Critical error occurred', {
  ariaProps: {
    role: 'alert',
    'aria-live': 'assertive',
  },
});

// Don't announce to screen readers
toast('Decorative notification', {
  ariaProps: {
    role: 'status',
    'aria-live': 'off',
  },
});

ariaProps

object

ARIA attributes for accessibility.

{
  role: 'status' | 'alert';
  'aria-live': 'assertive' | 'off' | 'polite';
}

Default: { role: 'status', 'aria-live': 'polite' }

ARIA Guidelines

role=“status”: Use for informational messages that don’t require immediate attention.role=“alert”: Use for important messages that require immediate attention (errors, warnings).aria-live=“polite”: Announces when screen reader is idle (default, non-intrusive).aria-live=“assertive”: Announces immediately, interrupting current speech.aria-live=“off”: Doesn’t announce to screen readers.

// Recommended settings
toast.success('Saved', {
  ariaProps: { role: 'status', 'aria-live': 'polite' },
});

toast.error('Error!', {
  ariaProps: { role: 'alert', 'aria-live': 'assertive' },
});

Toast ID

Provide a custom ID for updating or dismissing specific toasts:

// Create with custom ID
toast.loading('Processing...', { id: 'process-123' });

// Update the same toast
toast.success('Complete!', { id: 'process-123' });

// Or dismiss it
toast.dismiss('process-123');

string

Custom identifier for the toast. If omitted, a unique ID is generated automatically.Use custom IDs to:

Update existing toasts
Dismiss specific toasts
Prevent duplicate toasts

Reusing the same id updates the existing toast instead of creating a new one.

Global Defaults

Set defaults for all toasts via the Toaster component:

<Toaster
  position="top-center"
  toastOptions={{
    duration: 5000,
    style: {
      background: '#363636',
      color: '#fff',
      'font-family': 'system-ui',
    },
    className: 'my-toast',
    iconTheme: {
      primary: '#fff',
      secondary: '#363636',
    },
    ariaProps: {
      role: 'status',
      'aria-live': 'polite',
    },
    unmountDelay: 300,
  }}
/>

Individual toast options override these global defaults.

Complete Example

import { toast, Toaster } from 'solid-toast';

function App() {
  const showCustomToast = () => {
    toast.success('Fully customized!', {
      id: 'custom-success',
      duration: 3000,
      position: 'bottom-right',
      icon: '🚀',
      style: {
        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
        color: 'white',
        'border-radius': '12px',
        'box-shadow': '0 8px 16px rgba(0, 0, 0, 0.2)',
        padding: '16px 24px',
        'font-weight': '600',
      },
      className: 'custom-success-toast',
      iconTheme: {
        primary: '#ffffff',
        secondary: '#667eea',
      },
      ariaProps: {
        role: 'status',
        'aria-live': 'polite',
      },
      unmountDelay: 400,
    });
  };
  
  return (
    <>
      <Toaster position="top-center" />
      <button onClick={showCustomToast}>Show Toast</button>
    </>
  );
}

Get Started

Core Concepts

Guides

API Reference

Examples

Overview

ToastOptions Interface

Styling Options

Custom Styles

CSS Classes

Icon Customization

Custom Icons

Icon Theme

Duration

Position

Unmount Delay

Accessibility

ARIA Properties

Toast ID

Global Defaults

Complete Example

See Also

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

API Reference

Examples

​Overview

​ToastOptions Interface

​Styling Options

​Custom Styles

​CSS Classes

​Icon Customization

​Custom Icons

​Icon Theme

​Duration

​Position

​Unmount Delay

​Accessibility

​ARIA Properties

​Toast ID

​Global Defaults

​Complete Example

​See Also

Build docs developers (and LLMs) love

Overview

ToastOptions Interface

Styling Options

Custom Styles

CSS Classes

Icon Customization

Custom Icons

Icon Theme

Duration

Position

Unmount Delay

Accessibility

ARIA Properties

Toast ID

Global Defaults

Complete Example

See Also