0
# Zag.js Dialog
1
2
Zag.js Dialog provides a headless, framework-agnostic dialog (modal) component implemented as a finite state machine. It delivers accessible dialog functionality following WAI-ARIA authoring practices, with complete keyboard interactions, focus management, and ARIA roles/attributes handled automatically.
3
4
## Package Information
5
6
- **Package Name**: @zag-js/dialog
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @zag-js/dialog`
10
11
## Core Imports
12
13
```typescript
14
import { machine, connect, anatomy, props, splitProps } from "@zag-js/dialog";
15
import type { Api, Props, Service, ElementIds, OpenChangeDetails } from "@zag-js/dialog";
16
import type { FocusOutsideEvent, InteractOutsideEvent, PointerDownOutsideEvent } from "@zag-js/dialog";
17
```
18
19
For CommonJS:
20
21
```javascript
22
const { machine, connect, anatomy, props, splitProps } = require("@zag-js/dialog");
23
```
24
25
## Basic Usage
26
27
```typescript
28
import { machine, connect } from "@zag-js/dialog";
29
import { normalizeProps } from "@zag-js/react"; // or your framework adapter
30
31
function MyDialog() {
32
// Create machine instance
33
const [state, send] = useMachine(
34
machine({
35
id: "dialog-1",
36
onOpenChange: (details) => {
37
console.log("Dialog open:", details.open);
38
},
39
})
40
);
41
42
// Connect machine to UI
43
const api = connect(state, normalizeProps);
44
45
return (
46
<div>
47
<button {...api.getTriggerProps()}>Open Dialog</button>
48
49
{api.open && (
50
<div {...api.getPositionerProps()}>
51
<div {...api.getBackdropProps()} />
52
<div {...api.getContentProps()}>
53
<h2 {...api.getTitleProps()}>Dialog Title</h2>
54
<p {...api.getDescriptionProps()}>Dialog content goes here</p>
55
<button {...api.getCloseTriggerProps()}>Close</button>
56
</div>
57
</div>
58
)}
59
</div>
60
);
61
}
62
```
63
64
## Architecture
65
66
Zag.js Dialog is built around several key components:
67
68
- **State Machine**: Core logic implemented as a finite state machine with states (open/closed), events, effects, and actions
69
- **Connect API**: Framework-agnostic connection layer that provides prop functions for UI elements
70
- **Anatomy System**: Structured component parts with consistent naming and behavior
71
- **Accessibility Layer**: Built-in ARIA roles, keyboard interactions, and focus management
72
- **Framework Adapters**: Integration with React, Vue, Solid, Svelte through separate adapter packages
73
74
## Capabilities
75
76
### Dialog State Machine
77
78
Core state machine that manages dialog open/closed states, handles events, and orchestrates all dialog behaviors including accessibility features.
79
80
```typescript { .api }
81
function machine(props: Props): Machine;
82
83
interface Machine extends StateMachine<DialogSchema> {
84
state: "open" | "closed";
85
send: (event: MachineEvent) => void;
86
}
87
88
interface MachineEvent {
89
type: "OPEN" | "CLOSE" | "TOGGLE" | "CONTROLLED.OPEN" | "CONTROLLED.CLOSE";
90
}
91
```
92
93
[Dialog State Machine](./machine.md)
94
95
### API Connection
96
97
Connection layer that transforms state machine into framework-agnostic prop functions for UI elements, providing complete accessibility and interaction handling.
98
99
```typescript { .api }
100
function connect<T extends PropTypes>(
101
service: Service<DialogSchema>,
102
normalize: NormalizeProps<T>
103
): Api<T>;
104
105
interface Api<T extends PropTypes> {
106
open: boolean;
107
setOpen: (open: boolean) => void;
108
getTriggerProps: () => T["button"];
109
getBackdropProps: () => T["element"];
110
getPositionerProps: () => T["element"];
111
getContentProps: () => T["element"];
112
getTitleProps: () => T["element"];
113
getDescriptionProps: () => T["element"];
114
getCloseTriggerProps: () => T["button"];
115
}
116
```
117
118
[API Connection Methods](./connect.md)
119
120
### Component Anatomy
121
122
Anatomical structure defining the dialog's component parts with consistent naming and CSS class generation.
123
124
```typescript { .api }
125
interface Anatomy {
126
trigger: AnatomyPart;
127
backdrop: AnatomyPart;
128
positioner: AnatomyPart;
129
content: AnatomyPart;
130
title: AnatomyPart;
131
description: AnatomyPart;
132
closeTrigger: AnatomyPart;
133
}
134
135
const anatomy: Anatomy;
136
```
137
138
### Event Types
139
140
Event types for dismissible interactions that can occur outside the dialog.
141
142
```typescript { .api }
143
type FocusOutsideEvent = CustomEvent & {
144
target: Element;
145
preventDefault: () => void;
146
};
147
148
type InteractOutsideEvent = CustomEvent & {
149
target: Element;
150
preventDefault: () => void;
151
};
152
153
type PointerDownOutsideEvent = CustomEvent & {
154
target: Element;
155
preventDefault: () => void;
156
};
157
```
158
159
### Props Utilities
160
161
Utility functions for working with dialog props in framework integrations.
162
163
```typescript { .api }
164
/**
165
* Props utility for type-safe prop definitions
166
*/
167
const props: PropsDefinition<Props>;
168
169
/**
170
* Split props utility for separating dialog props from other props
171
* @param allProps - Object containing all props
172
* @returns Tuple with [dialogProps, otherProps]
173
*/
174
const splitProps: <T extends Partial<Props>>(
175
allProps: T & Record<string, any>
176
) => [T, Record<string, any>];
177
178
interface PropsDefinition<T> {
179
/** Array of prop keys for type validation */
180
keys: (keyof T)[];
181
/** Type-safe prop object */
182
object: T;
183
}
184
```
185
186
## Types
187
188
### Configuration Props
189
190
```typescript { .api }
191
interface Props {
192
// Element IDs
193
ids?: ElementIds;
194
195
// State Management
196
open?: boolean;
197
defaultOpen?: boolean;
198
onOpenChange?: (details: OpenChangeDetails) => void;
199
200
// Behavior Configuration
201
modal?: boolean;
202
trapFocus?: boolean;
203
preventScroll?: boolean;
204
restoreFocus?: boolean;
205
closeOnInteractOutside?: boolean;
206
closeOnEscape?: boolean;
207
208
// Accessibility
209
role?: "dialog" | "alertdialog";
210
"aria-label"?: string;
211
212
// Focus Management
213
initialFocusEl?: () => MaybeElement;
214
finalFocusEl?: () => MaybeElement;
215
216
// Event Handlers
217
onInteractOutside?: (event: InteractOutsideEvent) => void;
218
onFocusOutside?: (event: FocusOutsideEvent) => void;
219
onPointerDownOutside?: (event: PointerDownOutsideEvent) => void;
220
onEscapeKeyDown?: (event: KeyboardEvent) => void;
221
onRequestDismiss?: () => void;
222
223
// Other
224
dir?: "ltr" | "rtl";
225
id?: string;
226
getRootNode?: () => Node | ShadowRoot | Document;
227
persistentElements?: () => Element[];
228
}
229
230
interface ElementIds {
231
trigger?: string;
232
positioner?: string;
233
backdrop?: string;
234
content?: string;
235
closeTrigger?: string;
236
title?: string;
237
description?: string;
238
}
239
240
interface OpenChangeDetails {
241
open: boolean;
242
}
243
244
type MaybeElement = Element | null | undefined;
245
```
246
247
### Service Types
248
249
```typescript { .api }
250
interface Service extends StateMachineService<DialogSchema> {
251
state: State;
252
send: (event: MachineEvent) => void;
253
context: Context;
254
prop: (key: string) => any;
255
scope: Scope;
256
}
257
258
interface DialogSchema {
259
props: Props;
260
state: "open" | "closed";
261
context: {
262
rendered: { title: boolean; description: boolean };
263
};
264
guard: "isOpenControlled";
265
effect: "trackDismissableElement" | "preventScroll" | "trapFocus" | "hideContentBelow";
266
action: "checkRenderedElements" | "syncZIndex" | "invokeOnClose" | "invokeOnOpen" | "toggleVisibility";
267
event: MachineEvent;
268
}
269
```