# gds-dialog **Class**: `GdsDialog` **Tag**: `` ## Properties > Some properties accept design token names. Use `get_tokens` with the appropriate category to discover valid token names and their resolved values. | Name | Type | Default | Description | |------|------|---------|-------------| | `open` | `boolean` | `-` | Whether the dialog is open. The state of the dialog can be controlled either by setting this property or by calling the `show()` and `close()` methods. When the state is explicitly changed by setting this prop, the state change cannot be cancelled by events. | | `heading` | `string \| undefined` | `-` | The dialog's heading. | | `variant` | `'default' \| 'slide-out'` | `-` | The dialog's variant. | | `placement` | `'initial' \| 'top' \| 'bottom' \| 'left' \| 'right'` | `-` | The dialog's placement. | | `scrollable` | `boolean` | `-` | Whether the inner content of the dialog should have scrollable overflow. Scroll will appear if the content exceeds the dialog's height, which can be controlled using the `height` property. This property have no effect if the `dialog` slot is used. In that case, you need to add overflow styles to the content inside the `dialog` slot. | | `closedby` | `'closerequest' \| 'none' \| 'any'` | `-` | Controls which user actions can close the dialog. Maps to the native `` `closedby` attribute. - `closerequest` (default): The dialog can be dismissed by platform close gestures (Escape key, iOS swipe, etc.). The browser's anti-abuse mechanism applies: after one cancelled close request, subsequent cancellations require a user activation in between. This ensures the best mobile UX. - `none`: The dialog can only be closed by developer-specified mechanisms (buttons, click outside, or programmatic API). A manual Escape key listener is added for desktop users, with fully cancellable behavior (no anti-abuse limit). Mobile platform close gestures may not work in this mode. - `any`: The dialog can also be dismissed by light dismiss (clicking outside). Note that gds-dialog already handles click-outside via its own mechanism. | | `width` | `string \| undefined` | `-` | Style Expression Property that controls the `width` property. Supports space tokens and all valid CSS `width` values. | | `'min-width'` | `string \| undefined` | `-` | Style Expression Property that controls the `min-width` property. Supports space tokens and all valid CSS `min-width` values. | | `'max-width'` | `string \| undefined` | `-` | Style Expression Property that controls the `max-width` property. Supports space tokens and all valid CSS `max-width` values. | | `'inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `inline-size` property. Supports space tokens and all valid CSS `inline-size` values | | `'min-inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `min-inline-size` property. Supports space tokens and all valid CSS `min-inline-size` values. | | `'max-inline-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `max-inline-size` property. Supports space tokens and all valid CSS `max-inline-size` values. | | `height` | `string \| undefined` | `-` | Style Expression Property that controls the `height` property. Supports space tokens and all valid CSS `height` values. | | `'min-height'` | `string \| undefined` | `-` | Style Expression Property that controls the `min-height` property. Supports space tokens and all valid CSS `min-height` values. | | `'max-height'` | `string \| undefined` | `-` | Style Expression Property that controls the `max-height` property. Supports space tokens and all valid CSS `max-height` values. | | `'block-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `block-size` property. Supports space tokens and all valid CSS `block-size` values. | | `'min-block-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `min-block-size` property. Supports space tokens and all valid CSS `min-block-size` values. | | `'max-block-size'` | `string \| undefined` | `-` | Style Expression Property that controls the `max-block-size` property. Supports space tokens and all valid CSS `max-block-size` values. | | `padding` | `string \| undefined` | `-` | Style Expression Property that controls the `padding` property. Only accepts space tokens. | | `'padding-inline'` | `string \| undefined` | `-` | Style Expression Property that controls the `padding-inline` property. Only accepts space tokens. | | `'padding-block'` | `string \| undefined` | `-` | Style Expression Property that controls the `padding-block` property. Only accepts space tokens. | | `syncFirstRender` | `boolean` | `-` | Force the element to perform a synchronous first render and apply style expression properties in `connectedCallback`. This guarantees that the child DOM always remains projected in DOM, since the element will attach the shadowRoot and run the first render pass in the same event loop cycle, and that declarative layout will be applied once slotted DOM is projected. Note: This will cause the first render pass to be blocking. Use sparingly and only when necessary, such as when the element needs to be measured synchronously after being added to the DOM. | ## Events | Name | Type | Description | |------|------|-------------| | `gds-ui-state` | `CustomEvent` | Fired when the dialog is opened or closed. Can be cancelled to prevent the dialog from closing. | | `gds-close` | `CustomEvent` | Fired when the dialog is closed | | `gds-show` | `CustomEvent` | Fired when the dialog is opened | ## Slots | Name | Description | |------|-------------| | `(default)` | The content of the dialog | | `trigger` | The trigger button for the dialog | | `footer` | The footer of the dialog | | `dialog` | Complete override of the dialog content, including header and footer | ## Methods ### `show(reason?: string): void` Opens the dialog. This is a programmatic API that always opens the dialog. Events are dispatched for notification when a reason is provided, but cancellation is not honored. **Parameters:** - `reason`: `string` _(optional)_ ### `close(reason?: string): void` Closes the dialog. This is a programmatic API that always closes the dialog. Events are dispatched for notification when a reason is provided, but cancellation is not honored. **Parameters:** - `reason`: `string` _(optional)_