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

# Window Object

> API reference for the Window object in WezTerm's Lua configuration

A `Window` object represents a GUI terminal window in WezTerm. It provides methods to interact with the window's state, manage tabs, access configuration, and control the user interface.

Window objects cannot be created directly in Lua code; they are typically passed to your code via event callbacks.

## How to Access

Window objects are commonly accessed through:

* Event callbacks (e.g., `update-status`, `window-config-reloaded`)
* The first parameter in many event handlers

```lua theme={null}
local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  -- window is a Window object
  window:set_right_status('Hello!')
end)
```

## Identification

### window:window\_id()

Returns the unique window identifier.

**Returns:** `number` - The window ID

```lua theme={null}
local id = window:window_id()
```

## Navigation Methods

### window:active\_tab()

Returns the currently active tab in this window.

**Returns:** `MuxTab | nil`

```lua theme={null}
local tab = window:active_tab()
if tab then
  local title = tab:get_title()
end
```

### window:active\_pane()

Returns the currently active pane in the active tab.

**Returns:** `Pane | nil`

```lua theme={null}
local pane = window:active_pane()
if pane then
  pane:send_text('echo hello\n')
end
```

### window:mux\_window()

Returns the [MuxWindow](mux-window) object for this GUI window.

**Returns:** `MuxWindow | nil`

```lua theme={null}
local mux_win = window:mux_window()
if mux_win then
  local tabs = mux_win:tabs()
end
```

## State and Configuration

### window:effective\_config()

Returns the effective configuration for this window, including any overrides.

**Returns:** `Config` - The merged configuration object

```lua theme={null}
local config = window:effective_config()
local font_size = config.font_size
```

### window:get\_config\_overrides()

Returns the table of configuration overrides set for this window.

**Returns:** `table`

```lua theme={null}
local overrides = window:get_config_overrides()
```

### window:set\_config\_overrides(overrides)

Sets configuration overrides for this specific window.

<ParamField path="overrides" type="table" required>
  Table of configuration values to override. Pass an empty table or `nil` to clear overrides.
</ParamField>

```lua theme={null}
-- Increase font size for this window only
window:set_config_overrides({
  font_size = 14.0,
  color_scheme = 'Dracula'
})

-- Clear overrides
window:set_config_overrides({})
```

### window:get\_appearance()

Returns the system appearance (light/dark mode).

**Returns:** `string` - Either "Light" or "Dark"

```lua theme={null}
local appearance = window:get_appearance()
if appearance == 'Dark' then
  -- Use dark theme
end
```

## Workspace

### window:active\_workspace()

Returns the name of the active workspace for this window.

**Returns:** `string`

```lua theme={null}
local workspace = window:active_workspace()
wezterm.log_info('Current workspace: ', workspace)
```

## Dimensions

### window:get\_dimensions()

Returns dimensional information about the window.

**Returns:** Table with fields:

* `pixel_width` - window width in pixels
* `pixel_height` - window height in pixels
* `dpi` - DPI of the screen the window is on
* `is_full_screen` - whether window is in full screen mode

```lua theme={null}
local dims = window:get_dimensions()
if dims.is_full_screen then
  wezterm.log_info('Window is fullscreen')
end
```

### window:set\_inner\_size(width, height)

Sets the inner size of the window in pixels.

<ParamField path="width" type="number" required>
  Width in pixels
</ParamField>

<ParamField path="height" type="number" required>
  Height in pixels
</ParamField>

```lua theme={null}
window:set_inner_size(800, 600)
```

### window:set\_position(x, y)

Sets the window position on screen.

<ParamField path="x" type="number" required>
  X coordinate in pixels
</ParamField>

<ParamField path="y" type="number" required>
  Y coordinate in pixels
</ParamField>

```lua theme={null}
window:set_position(100, 100)
```

## Window State

### window:is\_focused()

Returns whether this window currently has focus.

**Returns:** `boolean`

```lua theme={null}
if window:is_focused() then
  -- Window has keyboard focus
end
```

### window:focus()

Brings this window to the front and gives it keyboard focus.

```lua theme={null}
window:focus()
```

### window:maximize()

Maximizes the window.

```lua theme={null}
window:maximize()
```

### window:restore()

Restores the window from maximized or minimized state.

```lua theme={null}
window:restore()
```

### window:toggle\_fullscreen()

Toggles full screen mode.

```lua theme={null}
window:toggle_fullscreen()
```

## Status Bar

### window:set\_left\_status(text)

Sets the left status bar text.

<ParamField path="text" type="string | table" required>
  Text to display, or a table of formatted elements
</ParamField>

```lua theme={null}
-- Simple text
window:set_left_status('Left Status')

-- Formatted elements
window:set_left_status({
  {Background = {Color = 'blue'}},
  {Text = ' Left '},
})
```

### window:set\_right\_status(text)

Sets the right status bar text.

<ParamField path="text" type="string | table" required>
  Text to display, or a table of formatted elements
</ParamField>

```lua theme={null}
-- Simple text
window:set_right_status('Right Status')

-- With formatting
window:set_right_status({
  {Foreground = {Color = 'yellow'}},
  {Text = wezterm.strftime('%H:%M')},
})
```

## Keyboard State

### window:keyboard\_modifiers()

Returns the currently pressed keyboard modifiers.

**Returns:** Table with boolean fields:

* `CTRL`
* `ALT`/`OPT`
* `SHIFT`
* `SUPER`/`CMD`

```lua theme={null}
local mods = window:keyboard_modifiers()
if mods.CTRL then
  -- Ctrl key is pressed
end
```

### window:leader\_is\_active()

Returns whether the leader key is currently active.

**Returns:** `boolean`

```lua theme={null}
if window:leader_is_active() then
  window:set_right_status('LEADER')
end
```

### window:active\_key\_table()

Returns the name of the currently active key table, if any.

**Returns:** `string | nil`

```lua theme={null}
local key_table = window:active_key_table()
if key_table then
  window:set_right_status('Mode: ' .. key_table)
end
```

## Composition Status

### window:composition\_status()

Returns the input method composition status.

**Returns:** `string | nil` - The composition text, if active

```lua theme={null}
local comp = window:composition_status()
if comp then
  wezterm.log_info('Composing: ', comp)
end
```

## Selection and Clipboard

### window:get\_selection\_text\_for\_pane(pane)

Returns the selected text in a specific pane as plain text.

<ParamField path="pane" type="Pane" required>
  The pane to get selection from
</ParamField>

**Returns:** `string`

```lua theme={null}
local pane = window:active_pane()
local selection = window:get_selection_text_for_pane(pane)
```

### window:get\_selection\_escapes\_for\_pane(pane)

Returns the selected text with ANSI escape sequences preserved.

<ParamField path="pane" type="Pane" required>
  The pane to get selection from
</ParamField>

**Returns:** `string`

```lua theme={null}
local pane = window:active_pane()
local selection_with_colors = window:get_selection_escapes_for_pane(pane)
```

### window:copy\_to\_clipboard(text, clipboard?)

Copies text to the system clipboard.

<ParamField path="text" type="string" required>
  Text to copy
</ParamField>

<ParamField path="clipboard" type="string" optional>
  Clipboard to use: "Clipboard" (default), "PrimarySelection"
</ParamField>

```lua theme={null}
window:copy_to_clipboard('Hello, clipboard!')

-- Copy to primary selection (X11)
window:copy_to_clipboard('Selected text', 'PrimarySelection')
```

## Actions and Notifications

### window:perform\_action(action, pane)

Programmatically performs a key assignment action.

<ParamField path="action" type="KeyAssignment" required>
  The action to perform
</ParamField>

<ParamField path="pane" type="Pane" required>
  The pane to perform the action on
</ParamField>

**Returns:** `boolean` - Whether the action was handled

```lua theme={null}
local wezterm = require 'wezterm'
local act = wezterm.action

local pane = window:active_pane()
window:perform_action(act.SplitHorizontal{domain = 'CurrentPaneDomain'}, pane)
```

### window:toast\_notification(title, message, url?, timeout?)

Displays a toast notification.

<ParamField path="title" type="string" required>
  Notification title
</ParamField>

<ParamField path="message" type="string" required>
  Notification message
</ParamField>

<ParamField path="url" type="string" optional>
  URL to open when notification is clicked
</ParamField>

<ParamField path="timeout" type="number" optional>
  Timeout in milliseconds
</ParamField>

```lua theme={null}
window:toast_notification(
  'Build Complete',
  'Your build finished successfully',
  nil,
  5000
)
```

### window:current\_event()

Returns information about the current event being processed.

**Returns:** Table with event details

```lua theme={null}
local event = window:current_event()
if event then
  wezterm.log_info('Event: ', event)
end
```

## Example: Dynamic Status Bar

```lua theme={null}
local wezterm = require 'wezterm'

wezterm.on('update-status', function(window, pane)
  -- Left status: workspace and key table
  local left_status = ''
  local workspace = window:active_workspace()
  if workspace ~= 'default' then
    left_status = 'WS: ' .. workspace .. ' '
  end
  
  local key_table = window:active_key_table()
  if key_table then
    left_status = left_status .. 'Mode: ' .. key_table
  end
  
  if window:leader_is_active() then
    left_status = left_status .. ' LEADER'
  end
  
  window:set_left_status(left_status)
  
  -- Right status: time and battery
  local time = wezterm.strftime('%H:%M')
  window:set_right_status({
    {Foreground = {Color = '#8be9fd'}},
    {Text = time .. ' '},
  })
end)
```

## Example: Appearance-Based Theming

```lua theme={null}
local wezterm = require 'wezterm'

wezterm.on('window-config-reloaded', function(window)
  local appearance = window:get_appearance()
  local overrides = window:get_config_overrides() or {}
  
  if appearance:find('Dark') then
    overrides.color_scheme = 'Dracula'
  else
    overrides.color_scheme = 'Builtin Solarized Light'
  end
  
  window:set_config_overrides(overrides)
end)
```

## Example: Focus-Based Opacity

```lua theme={null}
local wezterm = require 'wezterm'

wezterm.on('window-focus-changed', function(window, pane)
  local overrides = window:get_config_overrides() or {}
  
  if window:is_focused() then
    overrides.window_background_opacity = 1.0
  else
    overrides.window_background_opacity = 0.8
  end
  
  window:set_config_overrides(overrides)
end)
```