npm-react-aria

1
# Toast Notifications
2

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

5
## Capabilities
6

7
### Toast
8

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

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

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

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

44
**Usage Example:**
45

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

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

55
  if (!isVisible) return null;
56

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

70
### Toast Region
71

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

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

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

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

103
**Usage Example:**
104

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

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

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

125
## Types
126

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

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

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