263 lines
8.8 KiB
Markdown
263 lines
8.8 KiB
Markdown
# Dialog
|
|
|
|
A window overlaid on either the primary window or another dialog window. Content behind a modal dialog is inert, meaning that users cannot interact with it.
|
|
|
|
## Import
|
|
|
|
```
|
|
Copyts
|
|
import { Dialog } from "@kobalte/core/dialog";
|
|
// or
|
|
import { Root, Trigger, ... } from "@kobalte/core/dialog";
|
|
// or (deprecated)
|
|
import { Dialog } from "@kobalte/core";
|
|
```
|
|
|
|
```
|
|
Copyts
|
|
import { Dialog } from "@kobalte/core/dialog";
|
|
// or
|
|
import { Root, Trigger, ... } from "@kobalte/core/dialog";
|
|
// or (deprecated)
|
|
import { Dialog } from "@kobalte/core";
|
|
```
|
|
|
|
## Features
|
|
|
|
- Follows the [WAI ARIA Dialog](https://www.w3.org/WAI/ARIA/apg/patterns/dialogmodal/) design pattern.
|
|
- Supports modal and non-modal modes.
|
|
- Provides screen reader announcements via rendered title and description.
|
|
- Focus is trapped and scrolling is blocked while it is open.
|
|
- Pressing `Esc` closes the dialog.
|
|
- Can be controlled or uncontrolled.
|
|
|
|
## Anatomy
|
|
|
|
The dialog consists of:
|
|
|
|
- **Dialog:** Contains all the parts of a dialog.
|
|
- **Dialog.Trigger:** The button that opens the dialog.
|
|
- **Dialog.Portal:** Portals its children into the `body` when the dialog is open.
|
|
- **Dialog.Overlay:** The layer that covers the inert portion of the view when the dialog is open.
|
|
- **Dialog.Content:** Contains the content to be rendered when the dialog is open.
|
|
- **Dialog.CloseButton:** The button that closes the dialog.
|
|
- **Dialog.Title:** An accessible title to be announced when the dialog is opened.
|
|
- **Dialog.Description:** An optional accessible description to be announced when the dialog is opened.
|
|
|
|
```
|
|
Copytsx
|
|
<Dialog>
|
|
<Dialog.Trigger />
|
|
<Dialog.Portal>
|
|
<Dialog.Overlay />
|
|
<Dialog.Content>
|
|
<Dialog.CloseButton />
|
|
<Dialog.Title />
|
|
<Dialog.Description />
|
|
</Dialog.Content>
|
|
</Dialog.Portal>
|
|
</Dialog>
|
|
```
|
|
|
|
```
|
|
Copytsx
|
|
<Dialog>
|
|
<Dialog.Trigger />
|
|
<Dialog.Portal>
|
|
<Dialog.Overlay />
|
|
<Dialog.Content>
|
|
<Dialog.CloseButton />
|
|
<Dialog.Title />
|
|
<Dialog.Description />
|
|
</Dialog.Content>
|
|
</Dialog.Portal>
|
|
</Dialog>
|
|
```
|
|
|
|
## Example
|
|
|
|
Open
|
|
|
|
index.tsxstyle.css
|
|
|
|
```
|
|
Copytsx
|
|
import { Dialog } from "@kobalte/core/dialog";
|
|
import { CrossIcon } from "some-icon-library";
|
|
import "./style.css";
|
|
|
|
function App() {
|
|
return (
|
|
<Dialog>
|
|
<Dialog.Trigger class="dialog__trigger">Open</Dialog.Trigger>
|
|
<Dialog.Portal>
|
|
<Dialog.Overlay class="dialog__overlay" />
|
|
<div class="dialog__positioner">
|
|
<Dialog.Content class="dialog__content">
|
|
<div class="dialog__header">
|
|
<Dialog.Title class="dialog__title">About Kobalte</Dialog.Title>
|
|
<Dialog.CloseButton class="dialog__close-button">
|
|
<CrossIcon />
|
|
</Dialog.CloseButton>
|
|
</div>
|
|
<Dialog.Description class="dialog__description">
|
|
Kobalte is a UI toolkit for building accessible web apps and design systems with
|
|
SolidJS. It provides a set of low-level UI components and primitives which can be the
|
|
foundation for your design system implementation.
|
|
</Dialog.Description>
|
|
</Dialog.Content>
|
|
</div>
|
|
</Dialog.Portal>
|
|
</Dialog>
|
|
);
|
|
}
|
|
```
|
|
|
|
```
|
|
Copytsx
|
|
import { Dialog } from "@kobalte/core/dialog";
|
|
import { CrossIcon } from "some-icon-library";
|
|
import "./style.css";
|
|
|
|
function App() {
|
|
return (
|
|
<Dialog>
|
|
<Dialog.Trigger class="dialog__trigger">Open</Dialog.Trigger>
|
|
<Dialog.Portal>
|
|
<Dialog.Overlay class="dialog__overlay" />
|
|
<div class="dialog__positioner">
|
|
<Dialog.Content class="dialog__content">
|
|
<div class="dialog__header">
|
|
<Dialog.Title class="dialog__title">About Kobalte</Dialog.Title>
|
|
<Dialog.CloseButton class="dialog__close-button">
|
|
<CrossIcon />
|
|
</Dialog.CloseButton>
|
|
</div>
|
|
<Dialog.Description class="dialog__description">
|
|
Kobalte is a UI toolkit for building accessible web apps and design systems with
|
|
SolidJS. It provides a set of low-level UI components and primitives which can be the
|
|
foundation for your design system implementation.
|
|
</Dialog.Description>
|
|
</Dialog.Content>
|
|
</div>
|
|
</Dialog.Portal>
|
|
</Dialog>
|
|
);
|
|
}
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Default open
|
|
|
|
An initial, uncontrolled open value can be provided using the `defaultOpen` prop.
|
|
|
|
```
|
|
Copytsx
|
|
<Dialog defaultOpen>...</Dialog>
|
|
```
|
|
|
|
```
|
|
Copytsx
|
|
<Dialog defaultOpen>...</Dialog>
|
|
```
|
|
|
|
### Controlled open
|
|
|
|
The `open` prop can be used to make the open state controlled. The `onOpenChange` event is fired when the user presses the trigger, close button or overlay, and receives the new value.
|
|
|
|
```
|
|
Copytsx
|
|
import { createSignal } from "solid-js";
|
|
|
|
function ControlledExample() {
|
|
const [open, setOpen] = createSignal(false);
|
|
|
|
return (
|
|
<Dialog open={open()} onOpenChange={setOpen}>
|
|
...
|
|
</Dialog>
|
|
);
|
|
}
|
|
```
|
|
|
|
```
|
|
Copytsx
|
|
import { createSignal } from "solid-js";
|
|
|
|
function ControlledExample() {
|
|
const [open, setOpen] = createSignal(false);
|
|
|
|
return (
|
|
<Dialog open={open()} onOpenChange={setOpen}>
|
|
...
|
|
</Dialog>
|
|
);
|
|
}
|
|
```
|
|
|
|
## API Reference
|
|
|
|
### Dialog
|
|
|
|
`Dialog` is equivalent to the `Root` import from `@kobalte/core/dialog` (and deprecated `Dialog.Root`).
|
|
|
|
| Prop | Description |
|
|
| --- | --- |
|
|
| open | `boolean`<br> The controlled open state of the dialog. |
|
|
| defaultOpen | `boolean`<br> The default open state when initially rendered. Useful when you do not need to control the open state. |
|
|
| onOpenChange | `(open: boolean) => void`<br> Event handler called when the open state of the dialog changes. |
|
|
| id | `string`<br> A unique identifier for the component. The id is used to generate id attributes for nested components. If no id prop is provided, a generated id will be used. |
|
|
| modal | `boolean`<br> Whether the dialog should be the only visible content for screen readers, when set to `true`: <br> \- interaction with outside elements will be disabled. <br> \- scroll will be locked. <br> \- focus will be locked inside the dialog content. <br> \- elements outside the dialog content will not be visible for screen readers. |
|
|
| preventScroll | `boolean`<br> Whether the scroll should be locked even if the dialog is not modal. |
|
|
| forceMount | `boolean`<br> Used to force mounting the dialog (portal, overlay and content) when more control is needed. Useful when controlling animation with SolidJS animation libraries. |
|
|
| translations | [`DialogIntlTranslations`](https://github.com/kobaltedev/kobalte/blob/main/packages/core/src/dialog/dialog.intl.ts)<br> Localization strings. |
|
|
|
|
### Dialog.Trigger
|
|
|
|
`Dialog.Trigger` consists of [Button](https://kobalte.dev/docs/core/components/button).
|
|
|
|
| Data attribute | Description |
|
|
| --- | --- |
|
|
| data-expanded | Present when the dialog is open. |
|
|
| data-closed | Present when the dialog is close. |
|
|
|
|
`Dialog.Content` and `Dialog.Overlay` shares the same data-attributes.
|
|
|
|
### Dialog.Content
|
|
|
|
| Prop | Description |
|
|
| --- | --- |
|
|
| onOpenAutoFocus | `(event: Event) => void`<br> Event handler called when focus moves into the component after opening. It can be prevented by calling `event.preventDefault`. |
|
|
| onCloseAutoFocus | `(event: Event) => void`<br> Event handler called when focus moves to the trigger after closing. It can be prevented by calling `event.preventDefault`. |
|
|
| onEscapeKeyDown | `(event: KeyboardEvent) => void`<br> Event handler called when the escape key is down. It can be prevented by calling `event.preventDefault`. |
|
|
| onPointerDownOutside | `(event: PointerDownOutsideEvent) => void`<br> Event handler called when a pointer event occurs outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
|
|
| onFocusOutside | `(event: FocusOutsideEvent) => void`<br> Event handler called when the focus moves outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
|
|
| onInteractOutside | `(event: InteractOutsideEvent) => void`<br> Event handler called when an interaction (pointer or focus event) happens outside the bounds of the component. It can be prevented by calling `event.preventDefault`. |
|
|
|
|
## Rendered elements
|
|
|
|
| Component | Default rendered element |
|
|
| --- | --- |
|
|
| `Dialog` | none |
|
|
| `Dialog.Trigger` | `button` |
|
|
| `Dialog.Portal` | `Portal` |
|
|
| `Dialog.Overlay` | `div` |
|
|
| `Dialog.Content` | `div` |
|
|
| `Dialog.CloseButton` | `button` |
|
|
| `Dialog.Title` | `h2` |
|
|
| `Dialog.Description` | `p` |
|
|
|
|
## Accessibility
|
|
|
|
### Keyboard Interactions
|
|
|
|
| Key | Description |
|
|
| --- | --- |
|
|
| `Space` | When focus is on the trigger, opens/closes the dialog. |
|
|
| `Enter` | When focus is on the trigger, opens/closes the dialog. |
|
|
| `Tab` | Moves focus to the next focusable element. |
|
|
| `Shift` \+ `Tab` | Moves focus to the previous focusable element. |
|
|
| `Esc` | Closes the dialog and moves focus to the trigger. |
|
|
|
|
Previous[←Context Menu](https://kobalte.dev/docs/core/components/context-menu)Next[Dropdown Menu→](https://kobalte.dev/docs/core/components/dropdown-menu) |