prompt

Category: Dialog Operations

Namespace: web.dialogs.prompt

Builder Core: 2026.05.01.1814

Description

Display a native modal input dialog that asks the user for a single line of text. Supports a caption, message label, default value, masked-input (password) mode with a "Show password" toggle, preset button groups, and a custom action-button label. Returns an object describing which button was clicked and the value the user entered.

The dialog blocks the app window until dismissed. Closing with Escape or the title-bar X is treated as a cancel.

Syntax

const result = await web.dialogs.prompt({
    caption:  string,    // window title bar
    message:  string,    // label text above the input field
    value:    string,    // default text in the input field
    password: boolean,   // true = masked input + "Show password" checkbox
    buttons:  string,    // preset button group (see below)
    button:   string     // custom OK-button label (paired with Cancel)
});

Parameters

buttons presets

If both button and buttons are provided, button wins — the dialog shows your custom action button plus a Cancel button.

Returns

Promise<{ button: string, value: string }>

A custom button label resolves to "ok" when clicked. If the user cancels (Cancel button, Escape, or X), button is "cancel" and value is "".

Examples

Simple text prompt

const result = await web.dialogs.prompt({
    caption: 'Enter Name',
    message: 'What is your name?',
    value:   'John'
});

if (result.button === 'ok') {
    console.log('Hello, ' + result.value);
}

Password prompt

const result = await web.dialogs.prompt({
    caption:  'Authentication',
    message:  'Enter your password:',
    password: true
});

if (result.button === 'ok') {
    await signIn(result.value);
}

Custom action-button label

const result = await web.dialogs.prompt({
    caption: 'License Key',
    message: 'Enter your license key:',
    button:  'Activate'
});

if (result.button === 'ok' && result.value) {
    await activateLicense(result.value);
}

Pre-filled default — rename file

const result = await web.dialogs.prompt({
    caption: 'Rename File',
    message: 'New file name:',
    value:   currentFileName
});

if (result.button === 'ok' && result.value && result.value !== currentFileName) {
    await web.files.fileRename({ oldPath: currentPath, newName: result.value });
}

Yes / No / Cancel with input

const result = await web.dialogs.prompt({
    caption: 'Save As',
    message: 'Save current document as:',
    value:   'untitled.txt',
    buttons: 'yesnocancel'
});

if (result.button === 'yes') await saveAs(result.value);
else if (result.button === 'no') await saveAsDefault();
// 'cancel' → do nothing

Chained login flow — handle cancel between steps

const user = await web.dialogs.prompt({
    caption: 'Sign In',
    message: 'Username:',
    button:  'Next'
});
if (user.button !== 'ok') return;

const pass = await web.dialogs.prompt({
    caption:  'Sign In',
    message:  'Password for ' + user.value + ':',
    password: true,
    button:   'Sign In'
});
if (pass.button !== 'ok') return;

await login(user.value, pass.value);

Use Cases

• Replace prompt() with a native-looking modal input dialog
• Collect a single value (filename, tag, label, license key) without building a custom HTML form
• Ask for credentials with a masked password field and "Show password" toggle
• Pair an input with a domain-specific action label ("Activate", "Sign In", "Rename")
• Combine input collection with Yes/No/Cancel branching in a single dialog

Notes

• The input field is always single-line. For multi-line input, build a custom HTML form.
• password: true automatically adds a "Show password as plain text" checkbox below the field.
• The button option always pairs your custom label with a Cancel button — there is no single-button-only custom mode. If you need OK-only behavior, use buttons: 'ok' with the default "OK" label.
• Cancel always returns { button: "cancel", value: "" } regardless of what the user typed before cancelling.
• The dialog is modal and centered on the owning app window.

Related Methods

• message — Native Windows Task Dialog (alert, confirm, custom buttons)
• openFile — Native Windows file open dialog
• saveFile — Native Windows file save dialog
• selectFolder — Native Windows folder picker