# Shape the window.

Choose a size, keep the page above your other windows, and return it to the main VS Code window.

## Focus the window first.

Click the floating window, then choose the action from the Command Palette.

Commands for the focused floating window

| To do this | Use |
| --- | --- |
| Step through size presets | **Porthole: Cycle Window Size** |
| Unpin or re-pin | **Porthole: Toggle Always on Top** |
| Return to the main window | **Porthole: Dock Back into Main Window**, or **Ctrl+Alt+M** (**⌃⌥M** on macOS) |

## Pick your sizes.

`porthole.sizes` defines the cycle. A new window opens at the first preset. These are the defaults:

```
"porthole.sizes": [
  { "name": "S", "width": 420, "height": 640 },
  { "name": "M", "width": 480, "height": 720 },
  { "name": "L", "width": 640, "height": 900 }
]
```

Dimensions are pixels. VS Code will not make a window smaller than **400 × 270**. Cycling size reopens the page at the next preset.

If a page was opened through an outside link with an explicit size, the next cycle starts at your first preset.

## Choose where it opens.

`porthole.position` defaults to `null`, which lets VS Code center the window on the current window. To choose screen coordinates:

```
"porthole.position": { "x": 40, "y": 80 }
```

`porthole.compact` and `porthole.alwaysOnTop` both default to `true`. They choose how a window opens. The pin command changes the focused window.

## Keep one tab in view.

Choosing **Keep Compact** at the first-use prompt lets Porthole configure VS Code’s `workbench.editor.autoLockGroups` setting. It writes only the integrated-browser and Markdown-preview entries, and tells you when it changes a setting.

Some extensions open editors by column number, which can still place a second tab in a floating window. `porthole.keepToOneTab` decides what happens:

- `move` — move the editor to the main window, keeping its cursor. The default.
- `ask` — ask each time.
- `off` — leave it in the floating window.

An editor with unsaved changes is always left where it is.

## If the preset does not apply.

Exact sizing relies on an internal VS Code command. If that call fails or Porthole detects no new window, it tries opening the page through separate commands, without applying your requested size. Check the **Porthole** output channel if no window appears.

Set `porthole.useInternalCommand` to `false` to skip the internal sizing command and use this fallback for new windows. Size presets then do not apply. See [Settings and troubleshooting](https://jlumbroso.github.io/porthole-docs/settings-and-troubleshooting.html) for the available controls and known limits.

## Chapter notes

**Focus first**

Click the floating window before using its size, pin, or dock command. With several windows open, make the intended window active.

**Minimum size**

VS Code will not make the window smaller than 400 × 270 pixels. The default presets are 420 × 640, 480 × 720, and 640 × 900.

**Exact sizes**

Preset sizing relies on an internal VS Code command. If it fails, Porthole tries another way to open the window, without applying the requested size.

For Porthole 0.4.0. Updated 19 October 2026. [Online chapter](https://jlumbroso.github.io/porthole-docs/window-controls.html). [Source reference](https://github.com/jlumbroso/porthole/blob/v0.4.0/package.json).