# Dialog

Native popups for messages, errors, confirmations, and file explorer operations.

## Methods

### <mark style="color:purple;">Show Open Dialog</mark>

Shows an open file dialog.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.dialog.showOpen({ arguments })
```

**Arguments**

* `title` <mark style="color:green;">String</mark> (Optional)\
  A title for the dialog box.
* `defaultPath` <mark style="color:green;">String</mark> (Optional)

  Which directory the file explorer will open on.
* `buttonLabel` <mark style="color:green;">String</mark> (Optional)

  Custom label for the confirmation button. A default label will be used if empty.
* `filters` Array Of [<mark style="color:blue;">Electron.FileFilter</mark>](https://www.electronjs.org/docs/latest/api/structures/file-filter) (Optional)\
  Optionally filter files to open by.
* `openFile` <mark style="color:green;">Boolean</mark> (Optional)\
  Allows files to be selected.
* `openDirectory` <mark style="color:green;">Boolean</mark> (Optional)\
  Allow directories to be selected.
* `multiSelections` <mark style="color:green;">Boolean</mark> (Optional)\
  Allow multiple paths to be selected.
* `showHiddenFiles` <mark style="color:green;">Boolean</mark> (Optional)\
  Show hidden files in dialog.
* `createDirectory` <mark style="color:green;">Boolean</mark> ***macOS*** (Optional)\
  Allow creating new directories from dialog.
* `promptToCreate` <mark style="color:green;">Boolean</mark> ***Windows*** (Optional)\
  Prompt for creation if the file path entered in the dialog does not exist. This does not actually create the file at the path but allows non-existent paths to be returned that should be created by the application.
* `treatPackageAsDirectory` <mark style="color:green;">Boolean</mark> ***macOS*** (Optional)\
  Treat packages, such as .app folders as a directory instead of a file.
* `dontAddToRecent` <mark style="color:green;">Boolean</mark> ***Windows*** (Optional)\
  Do not add the item being opened to the recent documents list.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
* `canceled` <mark style="color:green;">Boolean</mark>\
  Whether or not the dialog was canceled.
* `filePaths` Array of <mark style="color:green;">Strings</mark>\
  An array of file paths chosen by the user. If the dialog is cancelled this will be an empty array.

**Example**

{% code overflow="wrap" %}

```javascript
const dialogOptions = {
    filters: [
        { name: 'Images', extensions: ['jpg', 'png', 'gif'] },
        { name: 'Movies', extensions: ['mkv', 'avi', 'mp4'] },
        { name: 'Custom File Type', extensions: ['as'] },
        { name: 'All Files', extensions: ['*'] }      
    ],
    multiSelections: true
};

const result = await window.deskifier.dialog.showOpen(dialogOptions);

console.log(result.filePaths)
//["C:\\Users\\Example\\Path.jpg", "C:\\Users\\Example\\Path2.jpg"]
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

### <mark style="color:purple;">Show Save Dialog</mark>

Shows a save file dialog.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.dialog.showSave({ arguments })
```

**Arguments**

* `title` <mark style="color:green;">String</mark> (Optional)\
  A title for the dialog box.
* `defaultPath` <mark style="color:green;">String</mark> (Optional)

  Absolute directory path, absolute file path, or file name to use by default.
* `buttonLabel` <mark style="color:green;">String</mark> (Optional)

  Custom label for the confirmation button. A default label will be used if empty.
* `filters` Array Of [<mark style="color:blue;">Electron.FileFilter</mark>](https://www.electronjs.org/docs/latest/api/structures/file-filter) (Optional)\
  Optionally filter files to open by.
* `message` <mark style="color:green;">String</mark> (Optional)\
  Message to display above text fields.
* `nameFieldLabel` <mark style="color:green;">String</mark> (Optional)\
  Custom label for the text displayed in front of the filename text field.
* `showsTagField` <mark style="color:green;">Boolean</mark> (Optional)\
  Show the tags input box, defaults to true.
* `showHiddenFiles` <mark style="color:green;">Boolean</mark> (Optional)\
  Show hidden files in dialog.
* `createDirectory` <mark style="color:green;">Boolean</mark> ***macOS*** (Optional)\
  Allow creating new directories from dialog.
* `treatPackageAsDirectory` <mark style="color:green;">Boolean</mark> ***macOS*** (Optional)\
  Treat packages, such as .app folders as a directory instead of a file.
* `dontAddToRecent` <mark style="color:green;">Boolean</mark> ***Windows*** (Optional)\
  Do not add the item being opened to the recent documents list.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
* `canceled` <mark style="color:green;">Boolean</mark>\
  Whether or not the dialog was canceled.
* `filePath` <mark style="color:green;">String</mark>\
  File path chosen by the user. If the dialog is cancelled this will be an empty string.

**Example**

{% code overflow="wrap" %}

```javascript
const result = await window.deskifier.dialog.showSave();

console.log(result.filePath)
//["C:\\Users\\Example\\Path.jpg"]
```

{% endcode %}
{% endtab %}
{% endtabs %}

***

### <mark style="color:purple;">Show Message Box</mark>

Shows a message box.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.dialog.showMessageBox({ arguments })
```

**Arguments**

* `message` <mark style="color:green;">String</mark> (Required)\
  Content of the message box.
* `type` <mark style="color:green;">String</mark> (Optional)

  Can be `none`, `info`, `error`, `question` or `warning`. On Windows, question displays the same icon as `info`.
* `buttons` Array Of <mark style="color:green;">String</mark> (Optional)

  Array of texts for buttons. On Windows, an empty array will result in one button labeled "OK".
* `defaultId` <mark style="color:green;">Number</mark> (Optional)\
  Index of the button in the buttons array which will be selected by default when the message box opens.
* `title` <mark style="color:green;">String</mark> (Optional)\
  Title of the message box, some platforms will not show it.
* `detail` <mark style="color:green;">String</mark> (Optional)\
  Extra information of the message.
* `checkboxLabel` <mark style="color:green;">String</mark> (Optional)\
  If provided, the message box will include a checkbox with the given label.
* `checkboxChecked` <mark style="color:green;">Boolean</mark> (Optional)\
  Initial checked state of the checkbox. `false` by default.
* `cancelId` <mark style="color:green;">Number</mark> (Optional)\
  The index of the button to be used to cancel the dialog, via the `Esc` key. By default this is assigned to the first button with "cancel" or "no" as the label. If no such labeled buttons exist and this option is not set, `0` will be used as the return value.
* `noLink` <mark style="color:green;">Boolean</mark> (Optional)\
  On Windows Electron will try to figure out which one of the `buttons` are common buttons (like "Cancel" or "Yes"), and show the others as command links in the dialog. This can make the dialog appear in the style of modern Windows apps. If you don't like this behavior, you can set `noLink` to `true`.
* `normalizeAccessKeys` <mark style="color:green;">Boolean</mark> (Optional)\
  Normalize the keyboard access keys across platforms. Default is `false`. Enabling this assumes `&` is used in the button labels for the placement of the keyboard shortcut access key and labels will be converted so they work correctly on each platform, `&` characters are removed on macOS, converted to `_` on Linux, and left untouched on Windows. For example, a button label of `Vie&w` will be converted to `Vie_w` on Linux and `View` on macOS and can be selected via `Alt-W` on Windows and Linux.

**Returns**

* `success` <mark style="color:green;">Boolean</mark>\
  If the action was successful.
* `message` <mark style="color:green;">String</mark>\
  Additional confirmation, or error details if action was unsuccessful.
* `response` <mark style="color:green;">Number</mark>\
  The index of the clicked button.
* `checkboxChecked` <mark style="color:green;">Boolean</mark>\
  The checked state of the checkbox if `checkboxLabel` was set. Otherwise `false`.
  {% endtab %}
  {% endtabs %}

***

### <mark style="color:purple;">Show Error Box</mark>

Displays a modal dialog that shows an error message.

{% tabs %}
{% tab title="JavaScript" %}

```javascript
await window.deskifier.dialog.showError({ arguments })
```

**Arguments**

* `title` <mark style="color:green;">String</mark> (Required)\
  The title to display in the error box.
* `content` <mark style="color:green;">String</mark> (Required)

  The text content to display in the error box.
  {% endtab %}
  {% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://deskifier.gitbook.io/deskifier/dialog.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.