Windowless mode

Equo Chromium offers a Windowless Mode, a headless version of the Chromium browser engine that runs without displaying a UI window. This makes it perfect for background tasks like automation, content processing, or rendering HTML offscreen, all without loading a full graphical environment.

Since there’s no visible interface, Windowless mode is much faster and lighter than a normal browser. It’s ideal for:

  • - Automated web testing

  • - Web scraping and data extraction

  • - HTML layout validation and performance profiling

  • - Offscreen rendering and JS evaluation

How Windowless mode works

When you use Windowless Mode, Equo Chromium still runs under the hood, but its rendering is done offscreen. You can interact with it programmatically without opening a browser window. This works in both SWT-based apps and plain Java applications.

Using Windowless mode in an SWT application

1. Import required classes

Start by importing the necessary SWT and ChromiumBrowser classes:

import org.eclipse.swt.*;
import org.eclipse.swt.events.*;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.*;

import com.equo.chromium.ChromiumBrowser;

2. Create the SWT shell

Set up your Display and Shell as the container for your UI:

    Display display = Display.getDefault();
    Shell shell = new Shell(display);
    shell.setLayout(new GridLayout(1, false));

4. Create a windowless Chromium browser

Instantiate a Chromium browser in windowless mode:

    ChromiumBrowser browser = ChromiumBrowser.windowless(
        "https://docs.equo.dev/main/getting-started/introduction.html"
    );

If you’re using Wayland and version =< 128.0.3, see the GTK and Wayland Support page.

5. Add a button to run JavaScript

If you want, you can create a button that executes JavaScript code in the browser.

    Button button = new Button(shell, SWT.PUSH);
    button.setText("Run JavaScript");
    button.addSelectionListener(new SelectionAdapter() {
        @Override
        public void widgetSelected(SelectionEvent e) {
            browser.executeJavacript("console.log(document.body.innerHTML)");
        }
    });

    // Create and open a shell.
    shell.pack();
    shell.open();

    // Start the event loop.
    while (!shell.isDisposed()) {
        if (!display.readAndDispatch())
            display.sleep();
    }

    display.dispose();

Using Windowless mode in a plain Java application

1. Import ChromiumBrowser

import com.equo.chromium.ChromiumBrowser;

2. Create a windowless browser instance

Instantiate Chromium with the desired URL and start the browser event loop. This will block the main thread until the browser exits.

ChromiumBrowser browser = ChromiumBrowser.windowless(
    "https://docs.equo.dev/main/getting-started/introduction.html"
);
// Start loop.
ChromiumBrowser.startBrowsers();

The Windowless mode can detect and adapt to the environment—SWT or standalone. On Linux, this means your application can run even without a display server (like X11 or Wayland), as long as no visible windows are created.

To explicitly force SWT integration, use:

-Dchromium.force_windowless_swt=true

Also note that:

[1] ChromiumBrowser.startBrowsers(); blocks the main thread until the browser is closed.

Checking Windowless compatibility

As of version 124.0.6, Equo Chromium provides a built-in method to verify that Windowless Mode can run on the current system:

ChromiumBrowser.compatibleWithHost().check();

This returns a CompletableFuture<String>. If it completes normally with an empty string, everything is good. If it completes exceptionally, it means there was an issue initializing the browser.

For full diagnostic details, a log file will be saved to:

~/.equo/compatibility_<DATE>.log