> Markdown version of [Secondary Windows](https://vaadin.com/docs/latest/tools/modernization-toolkit/swing-bridge/secondary-windows). Section index: [llms.txt](https://vaadin.com/docs/latest/tools/llms.txt)

# <a id="swing-bridge.secondary-windows"></a>Secondary Windows

When your Swing application opens a second top-level window on top of its main frame, SwingBridge surfaces that window in the browser as a Vaadin overlay. This applies to `JDialog`, `JFrame`, and `JWindow`. Popups, menus, and tooltips are handled separately and are always non-modal.

This page explains how the modality of a secondary window is decided, and how to control it for a `JFrame`.

## <a id="swing-bridge.secondary-windows.modality"></a>How Modality Is Decided

Whether a secondary window is rendered **modal** (it blocks interaction with everything behind it) or **modeless** (the rest of the UI stays interactive) depends on the window type:

| Window type          | Modality                                                                                                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `JDialog`            | Follows the dialog’s own modality — the value of its `isModal()` method. This mirrors what the Swing application already declared, so no extra configuration is needed.                                             |
| `JFrame` / `JWindow` | **Modeless by default.** A `JFrame` is never modal in Swing — it never blocks other windows — so SwingBridge renders it modeless to match. Opt a specific frame into modal rendering with the hint described below. |

## <a id="swing-bridge.secondary-windows.jframe-modality"></a>Controlling JFrame Modality

Some applications implement a secondary dialog as a `JFrame` rather than a `JDialog`, and still expect it to block the main frame. Because a `JFrame` has no modality property of its own, SwingBridge cannot infer this. Declare it explicitly by attaching a client-property hint to the frame’s root pane before the frame becomes visible.

The hint requires SwingBridge 1.2.1 or later. `WindowHints` lives in the `swing-bridge-annotations` JAR, the same compile-only JAR that holds the interoperability annotations. Add it to the Swing application’s build as described in [Adding the Annotations JAR to the Swing Application](https://vaadin.com/docs/latest/tools/modernization-toolkit/swing-bridge/interop.md#swing-bridge.interop.prerequisites.annotations). For Maven, that is:

```xml
<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>swing-bridge-annotations</artifactId>
    <version>1.3.0</version>
    <scope>provided</scope>
</dependency>
```

Keep its version in lockstep with SwingBridge on the Vaadin side. When the application runs embedded, SwingBridge supplies the `WindowHints` classes. Unlike the interoperability annotations, though, the code that sets the hint references `WindowHints.Modality` at runtime. If you still launch the Swing application as a standalone desktop application during the migration, put the JAR on the runtime classpath of that launch too, or the application fails with a `NoClassDefFoundError` when it sets the hint.

Then set the `WindowHints.MODALITY` client property to `MODAL`:

```java
import com.vaadin.swingbridge.window.WindowHints;

JFrame frame = new JFrame("Edit Customer");
// ... build the frame's content ...

// Render this frame as a modal overlay in SwingBridge.
frame.getRootPane().putClientProperty(WindowHints.MODALITY,
        WindowHints.Modality.MODAL);

frame.setVisible(true);
```

The hint travels with the window itself, so it takes effect no matter which Vaadin route or `SwingBridge` instance renders the frame — you set it once, in your Swing code, at the point where the frame is shown.

> **Note:** Set the hint **before** the frame becomes visible. SwingBridge reads it when it first surfaces the window, so changing it after the frame is shown has no effect.

To be explicit about a frame that should stay modeless, use `WindowHints.Modality.MODELESS`. Any `JFrame` or `JWindow` without the hint is already modeless, so this is only needed for readability.

> **Tip:** This hint has no effect on a `JDialog`. A dialog’s real modality (`isModal()`) always wins, so continue to use `setModal(…​)` on the `JDialog` itself.

## <a id="next-steps"></a>Next Steps

- Public API surface and lifecycle hooks: [Reference](https://vaadin.com/docs/latest/tools/modernization-toolkit/swing-bridge/reference.md).

- Call into Swing code and listen to Swing events from Vaadin: [Interoperability](https://vaadin.com/docs/latest/tools/modernization-toolkit/swing-bridge/interop.md).