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

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

local id = window:window_id()

Navigation Methods

window:active_tab()

Returns the currently active tab in this window.

Returns: MuxTab | nil

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

local pane = window:active_pane()
if pane then
  pane:send_text('echo hello\n')
end

window:mux_window()

Returns the MuxWindow object for this GUI window.

Returns: MuxWindow | nil

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

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

local overrides = window:get_config_overrides()

window:set_config_overrides(overrides)

Sets configuration overrides for this specific window.

overrides · table · required

Table of configuration values to override. Pass an empty table or nil to clear overrides.

-- 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”

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

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

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.

width · number · required

Width in pixels

height · number · required

Height in pixels

window:set_inner_size(800, 600)

window:set_position(x, y)

Sets the window position on screen.

x · number · required

X coordinate in pixels

y · number · required

Y coordinate in pixels

window:set_position(100, 100)

Window State

window:is_focused()

Returns whether this window currently has focus.

Returns: boolean

if window:is_focused() then
  -- Window has keyboard focus
end

window:focus()

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

window:focus()

window:maximize()

Maximizes the window.

window:maximize()

window:restore()

Restores the window from maximized or minimized state.

window:restore()

window:toggle_fullscreen()

Toggles full screen mode.

window:toggle_fullscreen()

Status Bar

window:set_left_status(text)

Sets the left status bar text.

text · string | table · required

Text to display, or a table of formatted elements

-- 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.

text · string | table · required

Text to display, or a table of formatted elements

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

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

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

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

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.

pane · Pane · required

The pane to get selection from

Returns: string

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.

pane · Pane · required

The pane to get selection from

Returns: string

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.

text · string · required

Text to copy

clipboard · string

Clipboard to use: “Clipboard” (default), “PrimarySelection”

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.

action · KeyAssignment · required

The action to perform

pane · Pane · required

The pane to perform the action on

Returns: boolean - Whether the action was handled

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.

title · string · required

Notification title

message · string · required

Notification message

url · string

URL to open when notification is clicked

timeout · number

Timeout in milliseconds

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

local event = window:current_event()
if event then
  wezterm.log_info('Event: ', event)
end

Example: Dynamic Status Bar

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

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

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)