> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/niri-wm/niri/llms.txt
> Use this file to discover all available pages before exploring further.

# Recent Windows

> Configure the recent windows switcher (Alt-Tab) in niri

<Info>
  Available since version 25.11
</Info>

In this section you can configure the recent windows switcher (Alt-Tab).

## Configuration Overview

Here is an outline of the available settings and their default values:

```kdl theme={null}
recent-windows {
    // off
    debounce-ms 750

    open-delay-ms 150

    highlight {
        active-color "#999999ff"
        urgent-color "#ff9999ff"
        padding 30
        corner-radius 0
    }

    previews {
        max-height 480
        max-scale 0.5
    }

    binds {
        Alt+Tab         { next-window; }
        Alt+Shift+Tab   { previous-window; }
        Alt+grave       { next-window     filter="app-id"; }
        Alt+Shift+grave { previous-window filter="app-id"; }

        Mod+Tab         { next-window; }
        Mod+Shift+Tab   { previous-window; }
        Mod+grave       { next-window     filter="app-id"; }
        Mod+Shift+grave { previous-window filter="app-id"; }
    }
}
```

### Disable Recent Windows

Set `off` to disable the recent windows switcher altogether:

```kdl theme={null}
recent-windows {
    off
}
```

## debounce-ms

<ParamField path="debounce-ms" type="number" default="750">
  Delay, in milliseconds, between the window receiving focus and getting "committed" to the recent windows list.
</ParamField>

When you want to focus some window, you might end up focusing some unrelated windows on the way:

* With keyboard navigation, the windows between your current one and the target one
* With `focus-follows-mouse`, the windows you happen to cross with the mouse pointer on the way to the target window

The debounce delay prevents those intermediate windows from polluting the recent windows list.

<Note>
  Some actions, like keyboard input into the target window, will skip this delay and commit the window to the list immediately. This way, the recent windows list stays responsive while not getting polluted too much with unintended windows.
</Note>

If you want windows to appear in recent windows right away, including intermediate windows, you can reduce the delay or set it to zero:

```kdl theme={null}
recent-windows {
    // Commit windows to the recent windows list as soon as they're focused,
    // with no debounce delay.
    debounce-ms 0
}
```

## open-delay-ms

<ParamField path="open-delay-ms" type="number" default="150">
  Delay, in milliseconds, between pressing the Alt-Tab bind and the recent windows switcher visually appearing on screen.
</ParamField>

The switcher is delayed by default so that quickly tapping Alt-Tab to switch windows wouldn't cause annoying fullscreen visual changes.

```kdl theme={null}
recent-windows {
    // Make the switcher appear instantly.
    open-delay-ms 0
}
```

## highlight

<ParamField path="highlight" type="object">
  Controls the highlight behind the focused window preview in the recent windows switcher.
</ParamField>

### Options

<ParamField path="active-color" type="color" default="#999999ff">
  Normal color of the focused window highlight.
</ParamField>

<ParamField path="urgent-color" type="color" default="#ff9999ff">
  Color of an urgent focused window highlight, also visible in a darker shade on unfocused windows.
</ParamField>

<ParamField path="padding" type="number" default="30">
  Padding of the highlight around the window preview, in logical pixels.
</ParamField>

<ParamField path="corner-radius" type="number" default="0">
  Corner radius of the highlight.
</ParamField>

### Example

```kdl theme={null}
recent-windows {
    // Round the corners on the highlight.
    highlight {
        corner-radius 14
    }
}
```

## previews

<ParamField path="previews" type="object">
  Controls the window previews in the switcher.
</ParamField>

### Options

<ParamField path="max-scale" type="number" default="0.5">
  Maximum scale of the window previews. Windows cannot be scaled bigger than this value.
</ParamField>

<ParamField path="max-height" type="number" default="480">
  Maximum height of the window previews. Further limits the size of the previews in order to occupy less space on large monitors.
</ParamField>

On smaller monitors, the previews will be primarily limited by `max-scale`, and on larger monitors they will be primarily limited by `max-height`.

The `max-scale` limit is imposed twice: on the final window scale, and on the window height which cannot exceed `monitor height × max scale`.

### Examples

```kdl theme={null}
recent-windows {
    // Make the previews smaller to fit more on screen.
    previews {
        max-height 320
    }
}
```

```kdl theme={null}
recent-windows {
    // Make the previews larger to see the window contents.
    previews {
        max-height 1080
        max-scale 0.75
    }
}
```

## binds

<ParamField path="binds" type="object">
  Configure binds that open and navigate the recent windows switcher.
</ParamField>

The defaults are `Alt+Tab` / `Mod+Tab` to switch across all windows, and `Alt+grave` / `Mod+grave` to switch between windows of the current application. Adding `Shift` will switch windows backwards.

<Warning>
  Adding the recent windows `binds {}` section to your config removes all default binds. You can copy the ones you need from the configuration overview at the top of this page.
</Warning>

```kdl theme={null}
recent-windows {
    // Even an empty binds {} section will remove all default binds.
    binds {
    }
}
```

### Available Actions

The available actions are `next-window` and `previous-window`. They can optionally have the following properties:

<ParamField path="filter" type="string">
  Set to `"app-id"` to filter the switcher to the windows of the currently selected application, as determined by the Wayland app ID.
</ParamField>

<ParamField path="scope" type="string">
  Sets the pre-selected scope when this bind is used to open the recent windows switcher. Options:

  * `"all"` - All windows
  * `"output"` - Windows on current output
  * `"workspace"` - Windows on current workspace
</ParamField>

### Example

```kdl theme={null}
recent-windows {
    // Pre-select the "Output" scope when switching windows.
    binds {
        Mod+Tab         { next-window     scope="output"; }
        Mod+Shift+Tab   { previous-window scope="output"; }
        Mod+grave       { next-window     scope="output" filter="app-id"; }
        Mod+Shift+grave { previous-window scope="output" filter="app-id"; }
    }
}
```

<Note>
  The recent windows binds have lower precedence than the normal binds, meaning that if you have `Alt+Tab` bound to something else in the normal binds, the `recent-windows` bind won't work. In this case, you can remove the conflicting normal bind.
</Note>

<Warning>
  All binds in this section must have a modifier key like `Alt` or `Mod` because the recent windows switcher remains open only while you hold any modifier key.
</Warning>

## Bindings Inside the Switcher

When the switcher is open, some hardcoded binds are available:

* `Escape` - Cancels the switcher
* `Enter` - Closes the switcher confirming the current window
* `A`, `W`, `O` - Select a specific scope
* `S` - Cycles between scopes (as indicated by the panel at the top)
* `←`, `→`, `Home`, `End` - Move the selection directionally

### Automatic Regular Binds

Additionally, certain regular binds will automatically work in the switcher:

* **Focus column left/right** and their variants - Will move the selection left/right inside the switcher
* **Focus column first/last** - Will move the selection to the first or last window
* **Close window** - Will close the window currently focused in the switcher
* **Screenshot** - Will open the screenshot UI

The way this works is by finding all regular binds corresponding to these actions and taking just the trigger key without modifiers.

<Tip>
  For example, if you have `Mod+Shift+C` bound to `close-window`, in the window switcher pressing `C` on its own will close the window.

  This means we don't need to hardcode things like HJKL directional movements. If you have, say, Colemak-DH MNEI binds instead, they will work for you in the window switcher (as long as they don't conflict with the hardcoded ones).
</Tip>