0
# SweetAlert2
1

2
SweetAlert2 is a beautiful, responsive, customizable and accessible (WAI-ARIA) replacement for JavaScript's popup boxes. It provides zero-dependency alert, confirm, prompt, and toast notifications with extensive customization options and comprehensive API controls.
3

4
## Package Information
5

6
- **Package Name**: sweetalert2
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install sweetalert2`
10
- **CDN**: Available via unpkg, jsDelivr, and other CDNs
11

12
## Core Imports
13

14
```typescript
15
import Swal from 'sweetalert2';
16
```
17

18
For CommonJS:
19

20
```javascript
21
const Swal = require('sweetalert2');
22
```
23

24
Alternative named import (ES modules):
25

26
```typescript
27
import { default as Swal } from 'sweetalert2';
28
```
29

30
## Basic Usage
31

32
```typescript
33
import Swal from 'sweetalert2';
34

35
// Simple alert
36
await Swal.fire('Hello world!');
37

38
// Alert with icon and text
39
await Swal.fire('Success!', 'Your changes have been saved.', 'success');
40

41
// Confirmation dialog
42
const result = await Swal.fire({
43
  title: 'Are you sure?',
44
  text: "You won't be able to revert this!",
45
  icon: 'warning',
46
  showCancelButton: true,
47
  confirmButtonText: 'Yes, delete it!'
48
});
49

50
if (result.isConfirmed) {
51
  Swal.fire('Deleted!', 'Your file has been deleted.', 'success');
52
}
53

54
// Toast notification
55
const Toast = Swal.mixin({
56
  toast: true,
57
  position: 'top-end',
58
  showConfirmButton: false,
59
  timer: 3000,
60
  timerProgressBar: true
61
});
62

63
Toast.fire({
64
  icon: 'success',
65
  title: 'Signed in successfully'
66
});
67

68
// Theme usage
69
await Swal.fire({
70
  title: 'Dark Theme Example',
71
  text: 'This popup uses the dark theme',
72
  icon: 'info',
73
  theme: 'dark'
74
});
75

76
// Declarative popup using bindClickHandler
77
Swal.bindClickHandler(); // Enables data-swal-template attribute
78
```
79

80
## Architecture
81

82
SweetAlert2 is built around several key components:
83

84
- **Main API**: The `Swal` namespace containing all static methods for creating and controlling popups
85
- **Options System**: Comprehensive configuration through the `SweetAlertOptions` interface
86
- **Promise-based**: All popup operations return promises with structured results
87
- **DOM Management**: Complete control over popup elements and styling
88
- **Event System**: Lifecycle hooks and event handlers for custom interactions
89
- **Timer System**: Built-in auto-close functionality with progress indicators
90

91
## Capabilities
92

93
### Core Dialog Methods
94

95
Primary methods for creating and displaying popups with various configurations and interaction patterns.
96

97
```typescript { .api }
98
function fire<T = any>(options: SweetAlertOptions): Promise<SweetAlertResult<Awaited<T>>>;
99
function fire<T = any>(title?: string, html?: string, icon?: SweetAlertIcon): Promise<SweetAlertResult<Awaited<T>>>;
100
function mixin(options: SweetAlertOptions): typeof Swal;
101
```
102

103
[Dialog Creation and Management](./dialog-management.md)
104

105
### DOM Element Access
106

107
Methods for accessing and manipulating specific popup elements for advanced customization and control.
108

109
```typescript { .api }
110
function getContainer(): HTMLElement | null;
111
function getPopup(): HTMLElement | null;
112
function getTitle(): HTMLElement | null;
113
function getConfirmButton(): HTMLButtonElement | null;
114
function getDenyButton(): HTMLButtonElement | null;
115
function getCancelButton(): HTMLButtonElement | null;
116
```
117

118
[DOM Element Access](./dom-access.md)
119

120
### State Management
121

122
Methods for checking popup state, controlling visibility, and managing loading states.
123

124
```typescript { .api }
125
function isVisible(): boolean;
126
function isLoading(): boolean;
127
function close(result?: Partial<SweetAlertResult>): void;
128
function update(options: Pick<SweetAlertOptions, SweetAlertUpdatableParameters>): void;
129
```
130

131
[State Management](./state-management.md)
132

133
### Input Handling
134

135
Comprehensive input support including validation, various input types, and input state management.
136

137
```typescript { .api }
138
function getInput(): HTMLInputElement | null;
139
function disableInput(): void;
140
function enableInput(): void;
141
function showValidationMessage(validationMessage: string): void;
142
function resetValidationMessage(): void;
143
```
144

145
[Input Handling and Validation](./input-validation.md)
146

147
### Timer Control
148

149
Auto-close functionality with timer controls and progress indication capabilities.
150

151
```typescript { .api }
152
function getTimerLeft(): number | undefined;
153
function stopTimer(): number | undefined;
154
function resumeTimer(): number | undefined;
155
function toggleTimer(): number | undefined;
156
function isTimerRunning(): boolean | undefined;
157
function increaseTimer(ms: number): number | undefined;
158
```
159

160
[Timer Control](./timer-control.md)
161

162
### Utility Functions
163

164
Advanced utility functions for parameter validation and declarative popup triggering.
165

166
```typescript { .api }
167
function bindClickHandler(attribute?: string): void;
168
function isValidParameter(paramName: string): paramName is keyof SweetAlertOptions;
169
function isUpdatableParameter(paramName: string): paramName is SweetAlertUpdatableParameters;
170
function argsToParams(params: SweetAlertArrayOptions | readonly [SweetAlertOptions]): SweetAlertOptions;
171
```
172

173
**Usage Examples:**
174

175
```typescript
176
// Enable declarative popups with custom attribute
177
Swal.bindClickHandler('data-my-alert');
178

179
// Validate parameter names programmatically  
180
if (Swal.isValidParameter('title')) {
181
  console.log('title is a valid parameter');
182
}
183

184
// Check if parameter can be updated
185
if (Swal.isUpdatableParameter('theme')) {
186
  Swal.update({ theme: 'dark' });
187
}
188

189
// Convert array parameters to options object
190
const options = Swal.argsToParams(['Hello', 'World', 'success']);
191
```
192

193
## Core Types
194

195
```typescript { .api }
196
interface SweetAlertResult<T = any> {
197
  readonly isConfirmed: boolean;
198
  readonly isDenied: boolean;
199
  readonly isDismissed: boolean;
200
  readonly value?: T;
201
  readonly dismiss?: Swal.DismissReason;
202
}
203

204
enum DismissReason {
205
  cancel = 'cancel',
206
  backdrop = 'backdrop',
207
  close = 'close',
208
  esc = 'esc',
209
  timer = 'timer'
210
}
211

212
type SweetAlertIcon = 'success' | 'error' | 'warning' | 'info' | 'question';
213

214
type SweetAlertPosition = 
215
  | 'top' | 'top-start' | 'top-end' | 'top-left' | 'top-right'
216
  | 'center' | 'center-start' | 'center-end' | 'center-left' | 'center-right'
217
  | 'bottom' | 'bottom-start' | 'bottom-end' | 'bottom-left' | 'bottom-right';
218

219
type SweetAlertInput = 
220
  | 'text' | 'email' | 'password' | 'number' | 'tel' | 'search' | 'range'
221
  | 'textarea' | 'select' | 'radio' | 'checkbox' | 'file' | 'url'
222
  | 'date' | 'datetime-local' | 'time' | 'week' | 'month';
223

224
type SweetAlertTheme = 
225
  | 'light' | 'dark' | 'auto' | 'minimal' | 'borderless' | 'embed-iframe' 
226
  | 'bulma' | 'bulma-light' | 'bulma-dark';
227

228
type SweetAlertEventName = 
229
  | 'didRender' | 'willOpen' | 'didOpen' | 'willClose' | 'didClose' | 'didDestroy';
230

231
type SweetAlertArrayOptions = readonly [string?, string?, SweetAlertIcon?];
232

233
type SweetAlertGrow = 'row' | 'column' | 'fullscreen' | false;
234
```
235

236
## Global Constants
237

238
```typescript { .api }
239
const version: string; // SweetAlert2 version string
240
```