0
# Toast Notifications
1

2
Toast notification system for displaying temporary messages and alerts with full accessibility support including screen reader announcements and proper focus management.
3

4
## Capabilities
5

6
### Toast
7

8
Provides toast notification behavior with automatic dismissal and accessibility features.
9

10
```typescript { .api }
11
/**
12
 * Provides toast notification behavior and accessibility
13
 * @param props - Toast configuration options
14
 * @param state - Toast state from useToastState
15
 * @param ref - Ref to the toast element
16
 * @returns Toast props and state
17
 */
18
function useToast(props: AriaToastProps, state: ToastState, ref: RefObject<Element>): ToastAria;
19

20
interface AriaToastProps {
21
  /** Priority level of the toast for screen readers */
22
  priority?: 'low' | 'high';
23
  /** Whether the toast can be dismissed by the user */
24
  isDismissible?: boolean;
25
  /** Handler called when the toast is dismissed */
26
  onClose?: () => void;
27
  /** Timeout in milliseconds before auto-dismissal */
28
  timeout?: number;
29
  /** Animation duration for enter/exit transitions */
30
  animation?: 'none' | 'slide' | 'fade';
31
}
32

33
interface ToastAria {
34
  /** Props to spread on the toast element */
35
  toastProps: DOMAttributes<Element>;
36
  /** Props for the close button (if dismissible) */
37
  closeButtonProps: DOMAttributes<Element>;
38
  /** Whether the toast is currently visible */
39
  isVisible: boolean;
40
}
41
```
42

43
**Usage Example:**
44

45
```typescript
46
import { useToast } from "react-aria";
47
import { useToastState } from "react-stately";
48

49
function Toast(props) {
50
  let state = useToastState(props);
51
  let ref = useRef();
52
  let { toastProps, closeButtonProps, isVisible } = useToast(props, state, ref);
53

54
  if (!isVisible) return null;
55

56
  return (
57
    <div {...toastProps} ref={ref} className="toast">
58
      <div className="toast-content">{props.children}</div>
59
      {props.isDismissible && (
60
        <button {...closeButtonProps} className="toast-close">
61
          ×
62
        </button>
63
      )}
64
    </div>
65
  );
66
}
67
```
68

69
### Toast Region
70

71
Manages a region containing multiple toasts with proper ARIA live region announcements.
72

73
```typescript { .api }
74
/**
75
 * Provides toast region behavior for managing multiple toast notifications
76
 * @param props - Toast region configuration
77
 * @param state - Toast region state from useToastRegionState
78
 * @param ref - Ref to the toast region element
79
 * @returns Toast region props
80
 */
81
function useToastRegion(props: AriaToastRegionProps, state: ToastRegionState, ref: RefObject<Element>): ToastRegionAria;
82

83
interface AriaToastRegionProps {
84
  /** Maximum number of toasts to display simultaneously */
85
  maxToasts?: number;
86
  /** Position of the toast region on screen */
87
  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
88
  /** Whether toasts should be announced to screen readers */
89
  hasLiveRegion?: boolean;
90
  /** ARIA live region politeness setting */
91
  politeness?: 'polite' | 'assertive';
92
}
93

94
interface ToastRegionAria {
95
  /** Props to spread on the toast region container */
96
  regionProps: DOMAttributes<Element>;
97
  /** Props for the ARIA live region */
98
  liveRegionProps: DOMAttributes<Element>;
99
}
100
```
101

102
**Usage Example:**
103

104
```typescript
105
import { useToastRegion } from "react-aria";
106
import { useToastRegionState } from "react-stately";
107

108
function ToastRegion(props) {
109
  let state = useToastRegionState(props);
110
  let ref = useRef();
111
  let { regionProps, liveRegionProps } = useToastRegion(props, state, ref);
112

113
  return (
114
    <div {...regionProps} ref={ref} className="toast-region">
115
      <div {...liveRegionProps} />
116
      {state.toasts.map((toast) => (
117
        <Toast key={toast.key} {...toast} />
118
      ))}
119
    </div>
120
  );
121
}
122
```
123

124
## Types
125

126
```typescript { .api }
127
interface ToastState {
128
  /** Collection of active toasts */
129
  toasts: Collection<ToastItem>;
130
  /** Add a new toast to the region */
131
  add(toast: ToastItem): string;
132
  /** Remove a toast by key */
133
  remove(key: string): void;
134
  /** Clear all toasts */
135
  clear(): void;
136
}
137

138
interface ToastRegionState {
139
  /** Collection of active toast regions */
140
  regions: Collection<ToastRegion>;
141
  /** Default toast region */
142
  defaultRegion: ToastRegion;
143
}
144

145
interface ToastItem {
146
  /** Unique identifier for the toast */
147
  key: string;
148
  /** Toast content */
149
  content: ReactNode;
150
  /** Toast priority level */
151
  priority: 'low' | 'high';
152
  /** Whether the toast is dismissible */
153
  isDismissible: boolean;
154
  /** Auto-dismiss timeout */
155
  timeout?: number;
156
}
157
```