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

# Appearance Configuration

> Customize colors, themes, backgrounds, transparency, and visual styles in WezTerm

## Color Schemes

WezTerm includes over 700 built-in color schemes from popular collections:

* [iTerm2-Color-Schemes](https://github.com/mbadolato/iTerm2-Color-Schemes)
* [base16](https://github.com/chriskempson/base16-schemes-source)
* [Gogh](https://gogh-co.github.io/Gogh/)
* [terminal.sexy](https://terminal.sexy/)

### Applying a Color Scheme

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.color_scheme = 'Dracula'

return config
```

<Tip>
  Browse all available color schemes at the [WezTerm Color Schemes Gallery](https://wezfurlong.org/wezterm/colorschemes/index.html).
</Tip>

### Dynamic Color Scheme Selection

<Tabs>
  <Tab title="Based on System Appearance">
    ```lua theme={null}
    local wezterm = require 'wezterm'
    local config = wezterm.config_builder()

    function scheme_for_appearance(appearance)
      if appearance:find 'Dark' then
        return 'Dracula'
      else
        return 'Solarized Light'
      end
    end

    config.color_scheme = scheme_for_appearance(wezterm.gui.get_appearance())

    return config
    ```
  </Tab>

  <Tab title="Random Color Scheme">
    ```lua theme={null}
    local wezterm = require 'wezterm'
    local config = wezterm.config_builder()

    -- Get all built-in color schemes
    local schemes = wezterm.get_builtin_color_schemes()
    local scheme_names = {}
    for name, _ in pairs(schemes) do
      table.insert(scheme_names, name)
    end

    -- Pick a random one
    math.randomseed(os.time())
    config.color_scheme = scheme_names[math.random(#scheme_names)]

    return config
    ```
  </Tab>
</Tabs>

## Custom Colors

Define your own colors or override specific colors from a scheme:

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.colors = {
  -- The default text color
  foreground = '#c0c0c0',
  -- The default background color
  background = '#1a1a1a',
  
  -- Cursor colors
  cursor_bg = '#52ad70',
  cursor_fg = '#000000',
  cursor_border = '#52ad70',
  
  -- Selection colors
  selection_fg = '#000000',
  selection_bg = '#fffacd',
  
  -- Scrollbar thumb color
  scrollbar_thumb = '#333333',
  
  -- Split separator color
  split = '#444444',
  
  -- ANSI color palette
  ansi = {
    '#000000', -- black
    '#cc0403', -- red
    '#19cb00', -- green
    '#cecb00', -- yellow
    '#0d73cc', -- blue
    '#cb1ed1', -- magenta
    '#0dcdcd', -- cyan
    '#dddddd', -- white
  },
  
  -- Bright ANSI colors
  brights = {
    '#767676', -- bright black
    '#f2201f', -- bright red
    '#23fd00', -- bright green
    '#fffd00', -- bright yellow
    '#1a8fff', -- bright blue
    '#fd28ff', -- bright magenta
    '#14ffff', -- bright cyan
    '#ffffff', -- bright white
  },
  
  -- Arbitrary colors (indices 16-255)
  indexed = { [136] = '#af8700' },
  
  -- Compose cursor color
  compose_cursor = '#ff9e64',
}

return config
```

### Color Formats

WezTerm supports multiple color formats:

<CodeGroup>
  ```lua Named Colors theme={null}
  config.colors = {
    foreground = 'silver',
    background = 'black',
  }
  ```

  ```lua Hex Colors theme={null}
  config.colors = {
    foreground = '#c0c0c0',
    background = '#000000',
  }
  ```

  ```lua RGB/RGBA theme={null}
  config.colors = {
    foreground = 'rgb(192, 192, 192)',
    background = 'rgba(0, 0, 0, 1.0)',
  }
  ```

  ```lua HSL Colors theme={null}
  config.colors = {
    foreground = 'hsl(235 100 50)',
    background = 'hsl(0deg 0% 0%)',
  }
  ```
</CodeGroup>

### Precedence: colors vs color\_scheme

<Note>
  Since version 20220903-194523-3bb1ed61, the `color_scheme` is applied first, then any colors defined in `colors` override the scheme values.
</Note>

```lua theme={null}
config.color_scheme = 'Dracula'

-- Override just the background
config.colors = {
  background = '#000000', -- Darker than Dracula's default
}
```

## Custom Color Schemes

Define reusable color schemes in your configuration:

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.color_schemes = {
  ['My Red Scheme'] = {
    background = '#330000',
    foreground = '#ffffff',
    ansi = {
      '#000000', '#dd0000', '#00dd00', '#dddd00',
      '#0000dd', '#dd00dd', '#00dddd', '#dddddd',
    },
    brights = {
      '#444444', '#ff0000', '#00ff00', '#ffff00',
      '#0000ff', '#ff00ff', '#00ffff', '#ffffff',
    },
  },
  ['My Blue Scheme'] = {
    background = '#000033',
    foreground = '#ffffff',
  },
}

config.color_scheme = 'My Red Scheme'

return config
```

## Tab Bar Appearance

### Tab Bar Styles

WezTerm offers two tab bar styles:

<Tabs>
  <Tab title="Fancy (Default)">
    ```lua theme={null}
    config.use_fancy_tab_bar = true
    config.window_frame = {
      font = wezterm.font { family = 'Roboto', weight = 'Bold' },
      font_size = 12.0,
      active_titlebar_bg = '#2b2042',
      inactive_titlebar_bg = '#2b2042',
    }
    ```
  </Tab>

  <Tab title="Retro">
    ```lua theme={null}
    config.use_fancy_tab_bar = false
    config.tab_bar_at_bottom = false
    ```
  </Tab>
</Tabs>

### Retro Tab Bar Colors

```lua theme={null}
config.use_fancy_tab_bar = false

config.colors = {
  tab_bar = {
    background = '#0b0022',
    
    active_tab = {
      bg_color = '#2b2042',
      fg_color = '#c0c0c0',
      intensity = 'Normal',
      underline = 'None',
      italic = false,
      strikethrough = false,
    },
    
    inactive_tab = {
      bg_color = '#1b1032',
      fg_color = '#808080',
    },
    
    inactive_tab_hover = {
      bg_color = '#3b3052',
      fg_color = '#909090',
      italic = true,
    },
    
    new_tab = {
      bg_color = '#1b1032',
      fg_color = '#808080',
    },
    
    new_tab_hover = {
      bg_color = '#3b3052',
      fg_color = '#909090',
      italic = true,
    },
  },
}
```

### Tab Bar Position and Visibility

```lua theme={null}
-- Hide tab bar when only one tab
config.hide_tab_bar_if_only_one_tab = true

-- Disable tab bar completely
config.enable_tab_bar = false

-- Place tab bar at bottom
config.tab_bar_at_bottom = true

-- Maximum tab width in cells (retro mode only)
config.tab_max_width = 32
```

## Window Transparency

### Background Opacity

```lua theme={null}
-- Fully opaque (default)
config.window_background_opacity = 1.0

-- Semi-transparent
config.window_background_opacity = 0.9

-- Very transparent
config.window_background_opacity = 0.5
```

<Note>
  Background opacity requires a compositing window manager (macOS, Windows, Wayland, or X11 with compositor).
</Note>

### Text Background Opacity

```lua theme={null}
-- Make text backgrounds less opaque
config.text_background_opacity = 0.7
```

### Platform-Specific Effects

<Tabs>
  <Tab title="macOS">
    ```lua theme={null}
    -- Background blur effect
    config.macos_window_background_blur = 30
    ```
  </Tab>

  <Tab title="Windows 11">
    ```lua theme={null}
    -- Acrylic, Mica, or Tabbed effects
    config.win32_system_backdrop = 'Acrylic'
    -- Options: 'Auto', 'Disable', 'Acrylic', 'Mica', 'Tabbed'

    config.win32_acrylic_accent_color = '#2b2042'
    ```
  </Tab>

  <Tab title="KDE (Linux)">
    ```lua theme={null}
    -- Enable blur effect
    config.kde_window_background_blur = 20
    ```
  </Tab>
</Tabs>

## Background Images

### Simple Background Image

```lua theme={null}
config.window_background_image = '/path/to/wallpaper.jpg'

-- Adjust image appearance
config.window_background_image_hsb = {
  brightness = 0.3,   -- Darken to 30%
  hue = 1.0,          -- No hue change
  saturation = 1.0,   -- No saturation change
}
```

### Advanced Multi-Layer Backgrounds

Create complex backgrounds with multiple layers:

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

config.background = {
  -- Background layer
  {
    source = { File = '/path/to/background.png' },
    width = '100%',
    height = '100%',
    opacity = 0.3,
    hsb = { brightness = 0.1 },
  },
  -- Overlay layer with parallax scrolling
  {
    source = { File = '/path/to/overlay.png' },
    width = '100%',
    repeat_x = 'NoRepeat',
    repeat_y = 'Mirror',
    vertical_align = 'Bottom',
    attachment = { Parallax = 0.2 }, -- Scrolls at 20% speed
    opacity = 0.5,
  },
  -- Gradient overlay
  {
    source = {
      Gradient = {
        colors = { '#000000', '#2b2042' },
        orientation = 'Vertical',
      },
    },
    width = '100%',
    height = '100%',
    opacity = 0.8,
  },
}

return config
```

### Background Layer Options

<Steps>
  <Step title="Source">
    Define the image source:

    ```lua theme={null}
    source = { File = '/path/to/image.png' }
    source = { Color = '#2b2042' }
    source = { Gradient = { preset = 'Warm' } }
    ```
  </Step>

  <Step title="Sizing">
    Control dimensions:

    ```lua theme={null}
    width = '100%'      -- Viewport percentage
    height = '50%'
    width = 800         -- Pixels
    height = '20cell'   -- Terminal cells
    width = 'Cover'     -- Scale to cover (default)
    width = 'Contain'   -- Scale to fit
    ```
  </Step>

  <Step title="Positioning">
    Align the layer:

    ```lua theme={null}
    horizontal_align = 'Center'  -- Left, Center, Right
    vertical_align = 'Middle'    -- Top, Middle, Bottom
    horizontal_offset = '10%'
    vertical_offset = '5cell'
    ```
  </Step>

  <Step title="Repetition">
    Control tiling:

    ```lua theme={null}
    repeat_x = 'Repeat'   -- Repeat, Mirror, NoRepeat
    repeat_y = 'NoRepeat'
    repeat_x_size = '100%'
    ```
  </Step>

  <Step title="Scrolling">
    Set scroll behavior:

    ```lua theme={null}
    attachment = 'Fixed'        -- Stays in place
    attachment = 'Scroll'       -- Scrolls 1:1
    attachment = { Parallax = 0.5 }  -- Scrolls at 50% speed
    ```
  </Step>
</Steps>

## Background Gradients

Create gradient backgrounds without image files:

<CodeGroup>
  ```lua Vertical Gradient theme={null}
  config.window_background_gradient = {
    colors = { '#1a1a1a', '#2b2042' },
    orientation = 'Vertical',
  }
  ```

  ```lua Horizontal Gradient theme={null}
  config.window_background_gradient = {
    colors = { '#0f0c29', '#302b63', '#24243e' },
    orientation = 'Horizontal',
  }
  ```

  ```lua Radial Gradient theme={null}
  config.window_background_gradient = {
    colors = { '#3b3052', '#1b1032' },
    orientation = {
      Radial = {
        cx = 0.5,  -- Center X (0.0 to 1.0)
        cy = 0.5,  -- Center Y
        radius = 1.0,
      },
    },
  }
  ```

  ```lua Preset Gradients theme={null}
  config.window_background_gradient = {
    preset = 'Warm',
    -- Presets: 'Warm', 'Cool', 'Ocean', 'Sunset', etc.
  }
  ```
</CodeGroup>

## Window Padding

Add spacing around terminal content:

```lua theme={null}
config.window_padding = {
  left = 20,
  right = 20,
  top = 10,
  bottom = 10,
}

-- Or use uniform padding
config.window_padding = {
  left = '1cell',
  right = '1cell',
  top = '0.5cell',
  bottom = '0.5cell',
}
```

## Pane Styling

### Inactive Pane Dimming

```lua theme={null}
-- Dim and desaturate inactive panes
config.inactive_pane_hsb = {
  saturation = 0.9,  -- Reduce color intensity
  brightness = 0.8,  -- Dim slightly
  hue = 1.0,         -- No hue shift
}

-- No dimming
config.inactive_pane_hsb = {
  saturation = 1.0,
  brightness = 1.0,
}
```

### Pane Borders

```lua theme={null}
config.colors = {
  split = '#444444',  -- Border color between panes
}
```

## Window Decorations

Control window frame appearance:

```lua theme={null}
-- Full decorations (default on most platforms)
config.window_decorations = 'TITLE | RESIZE'

-- No title bar
config.window_decorations = 'RESIZE'

-- No decorations at all
config.window_decorations = 'NONE'

-- Integrated buttons (macOS-style)
config.window_decorations = 'INTEGRATED_BUTTONS | RESIZE'
```

### Integrated Title Buttons

```lua theme={null}
config.integrated_title_buttons = { 'Hide', 'Maximize', 'Close' }
config.integrated_title_button_style = 'Windows'  -- or 'MacOsNative', 'Gnome'
config.integrated_title_button_alignment = 'Right'  -- or 'Left'

config.integrated_title_button_color = {
  text = '#cccccc',
  hover_bg = '#3b3052',
  hover_fg = '#ffffff',
}
```

## Cursor Appearance

```lua theme={null}
-- Cursor style
config.default_cursor_style = 'SteadyBlock'
-- Options: 'SteadyBlock', 'BlinkingBlock', 'SteadyUnderline',
--          'BlinkingUnderline', 'SteadyBar', 'BlinkingBar'

-- Cursor blink rate
config.cursor_blink_rate = 800  -- milliseconds
config.cursor_blink_ease_in = 'Constant'
config.cursor_blink_ease_out = 'Constant'

-- Cursor thickness (for bar/underline)
config.cursor_thickness = '2px'
```

## Complete Appearance Example

```lua theme={null}
local wezterm = require 'wezterm'
local config = wezterm.config_builder()

-- Color scheme
config.color_scheme = 'Dracula'

-- Override specific colors
config.colors = {
  background = '#1a1a1a',
  tab_bar = {
    background = '#1a1a1a',
    active_tab = {
      bg_color = '#2b2042',
      fg_color = '#c0c0c0',
    },
    inactive_tab = {
      bg_color = '#1a1a1a',
      fg_color = '#808080',
    },
  },
}

-- Transparency and effects
config.window_background_opacity = 0.95
config.macos_window_background_blur = 20

-- Window frame
config.window_decorations = 'RESIZE'
config.window_padding = {
  left = 20,
  right = 20,
  top = 10,
  bottom = 10,
}

-- Tab bar
config.use_fancy_tab_bar = true
config.hide_tab_bar_if_only_one_tab = true
config.tab_bar_at_bottom = false

-- Panes
config.inactive_pane_hsb = {
  saturation = 0.9,
  brightness = 0.8,
}

-- Cursor
config.default_cursor_style = 'BlinkingBar'
config.cursor_blink_rate = 500

return config
```