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, Chromium still runs under the hood, but its rendering is done offscreen. You can interact with it programmatically—load pages, run JavaScript, extract data—all without ever opening a browser window. This works in both SWT-based apps and plain Java applications.

Using Windowless mode in SWT applications

If you’re building with SWT, you can embed a Windowless browser alongside your widgets. Here’s how to do it:

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;

public class Windowless {
    public static void main(String[] args) throws ClassNotFoundException {
        ChromiumBrowser.earlyInit(); // [1]
        Display display = Display.getDefault();
        Shell shell = new Shell(display);
        shell.setLayout(new GridLayout(1, false));

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

        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)");
            }
        });

        shell.pack();
        shell.open();

        while (!shell.isDisposed()) {
            if (!display.readAndDispatch())
                display.sleep();
        }

        display.dispose();
    }
}

[1]Make sure to call ChromiumBrowser.earlyInit() before creating the UI.

Also pass the system property -Dchromium.init_threads=true at runtime.

On Linux, see the Wayland Support section for extra setup tips.

Using Windowless mode in a plain Java application

The following example runs a Chromium browser headlessly in a plain Java app:

import com.equo.chromium.ChromiumBrowser;

public class Windowless {
    public static void main(String[] args) {
        ChromiumBrowser browser = ChromiumBrowser.windowless(
            "https://docs.equo.dev/main/getting-started/introduction.html"
        );
        ChromiumBrowser.startBrowsers(); (1)
    }
}

Windowless Chromium 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

[1] ChromiumBrowser.startBrowsers(); xref[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