openUrl

Category: System Operations

Namespace: web.system.openUrl

Description

Opens a URL in the user's default web browser, or a mailto: link in their default email client. A clean, intent-revealing alternative to web.shell.execute for URL-specific use cases.

Syntax

const success = await web.system.openUrl(url);

Parameters

• url string (required) — The URL to open. Supports http://, https://, mailto:, and other URL schemes the OS can handle.

Note: This is a positional argument, NOT an options object.

Returns

Promise<boolean> — true if the OS accepted the request, false if the URL was empty or the OS could not handle it.

Examples

Open a webpage

await web.system.openUrl('https://www.google.com');

Open documentation link

document.getElementById('help-link').addEventListener('click', async () => {
    await web.system.openUrl('https://docs.example.com/user-guide');
});

Send email

await web.system.openUrl('mailto:support@example.com?subject=Help%20Request');

Conditional link with error handling

const opened = await web.system.openUrl('https://example.com/download');
if (!opened) {
    await web.dialogs.message({
        heading: 'Could not open browser',
        content: 'Please visit https://example.com/download manually.',
        icon: 'warning'
    });
}

Example complete

<!-- The Button -->
<button type="button" onclick="myFunction()">Run Code</button>

<!-- The Script -->
<script>
async function myFunction() {
const opened = await web.system.openUrl('https://example.com/download');
if (!opened) {
    await web.dialogs.message({
        heading: 'Could not open browser',
        content: 'Please visit https://example.com/download manually.',
        icon: 'warning'
    });
}

  }
</script>

Use Cases

• Open documentation, help pages, or changelogs
• Link to the developer's website or support page
• Open mailto: links for feedback or support emails
• Launch external web tools or dashboards
• Open GitHub/release pages from an "About" or "Update" dialog

Notes

• Uses ShellExecute('open', url) under the hood — the same mechanism Windows uses when you click a link
• Works with any URL scheme the OS has a handler for (http, https, mailto, tel, custom protocols)
• The promise resolves immediately once the OS accepts the request — it does not wait for the browser to load
• Returns false if the URL is empty; does not throw
• For opening local files or folders, use web.shell.showInExplorer() or web.shell.execute() instead

Related Methods

• web.shell.execute() — launch any executable or file with ShellExecute
• web.shell.showInExplorer() — open a file's location in Windows Explorer
• web.dialogs.message() — show a dialog with clickable <a href> hyperlinks