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

# Color Scheme Configuration

> Configure color schemes and palettes in WezTerm using Lua

# Color Scheme Configuration

WezTerm provides extensive color customization options, including built-in color schemes, custom palettes, and dynamic color configuration.

## Using Built-in Color Schemes

WezTerm includes hundreds of pre-configured color schemes. You can select one using the `color_scheme` option:

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

config.color_scheme = 'Dracula'

return config
```

<ParamField path="color_scheme" type="string" default="nil">
  The name of a built-in color scheme. When set, this overrides the `colors` configuration.
</ParamField>

### Popular Color Schemes

<CodeGroup>
  ```lua Dark Themes theme={null}
  config.color_scheme = 'Dracula'
  -- or
  config.color_scheme = 'Catppuccin Mocha'
  -- or
  config.color_scheme = 'Tokyo Night'
  -- or
  config.color_scheme = 'Nord'
  ```

  ```lua Light Themes theme={null}
  config.color_scheme = 'GitHub Light'
  -- or
  config.color_scheme = 'Solarized (light) (terminal.sexy)'
  -- or
  config.color_scheme = 'Catppuccin Latte'
  ```
</CodeGroup>

### Listing Available Color Schemes

You can list all available color schemes using:

```bash theme={null}
wezterm ls-color-schemes
```

Or programmatically in Lua:

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

for name, scheme in pairs(wezterm.color.get_builtin_schemes()) do
  wezterm.log_info('Color scheme: ' .. name)
end
```

## Custom Color Palettes

You can define your own color palette using the `colors` configuration option:

```lua theme={null}
config.colors = {
  -- The default text color
  foreground = '#d4d4d4',
  -- The default background color
  background = '#1e1e1e',

  -- Overrides the cell background color when the current cell is occupied by the cursor
  cursor_bg = '#52ad70',
  -- Overrides the text color when the current cell is occupied by the cursor
  cursor_fg = '#1e1e1e',
  -- Specifies the border color of the cursor when the cursor style is set to Block
  cursor_border = '#52ad70',

  -- The foreground color of selected text
  selection_fg = '#1e1e1e',
  -- The background color of selected text
  selection_bg = '#3a3d41',

  -- The color of the scrollbar "thumb"; the portion that represents the current viewport
  scrollbar_thumb = '#3a3d41',

  -- The color of the split lines between panes
  split = '#444444',

  -- ANSI color palette (colors 0-7)
  ansi = {
    '#1e1e1e', -- black
    '#f48771', -- red
    '#a1cd5e', -- green
    '#e4c877', -- yellow
    '#6ab0f3', -- blue
    '#f47590', -- magenta
    '#00bcd4', -- cyan
    '#d4d4d4', -- white
  },

  -- Bright ANSI colors (colors 8-15)
  brights = {
    '#8b8b8b', -- bright black
    '#f48771', -- bright red
    '#a1cd5e', -- bright green
    '#e4c877', -- bright yellow
    '#6ab0f3', -- bright blue
    '#f47590', -- bright magenta
    '#00bcd4', -- bright cyan
    '#ffffff', -- bright white
  },
}
```

### Color Palette Structure

<ParamField path="colors" type="table" default="nil">
  A table defining the color palette for the terminal.
</ParamField>

<ParamField path="colors.foreground" type="string">
  The default text color in hex format (e.g., `#d4d4d4`).
</ParamField>

<ParamField path="colors.background" type="string">
  The default background color in hex format.
</ParamField>

<ParamField path="colors.cursor_bg" type="string">
  The cursor background color.
</ParamField>

<ParamField path="colors.cursor_fg" type="string">
  The cursor foreground/text color.
</ParamField>

<ParamField path="colors.cursor_border" type="string">
  The cursor border color (when using block cursor).
</ParamField>

<ParamField path="colors.selection_fg" type="string">
  The text color for selected text.
</ParamField>

<ParamField path="colors.selection_bg" type="string">
  The background color for selected text.
</ParamField>

<ParamField path="colors.ansi" type="array">
  An array of 8 colors for the standard ANSI palette (colors 0-7).
</ParamField>

<ParamField path="colors.brights" type="array">
  An array of 8 colors for the bright ANSI palette (colors 8-15).
</ParamField>

### Indexed Colors

You can also define indexed colors for the 256-color palette:

```lua theme={null}
config.colors = {
  -- ... other colors ...
  indexed = {
    [16] = '#1a1a1a',
    [17] = '#2a2a2a',
    [52] = '#fbdada', -- Used by diff tools
    [88] = '#f6b6b6',
  },
}
```

<ParamField path="colors.indexed" type="table" default="{}">
  A table mapping color indices (16-255) to hex color values.
</ParamField>

<Note>
  Indices 0-15 should be specified using `ansi` and `brights` arrays, not the `indexed` table.
</Note>

## Tab Bar Colors

Customize the appearance of the tab bar:

```lua theme={null}
config.colors = {
  tab_bar = {
    -- The color of the strip that goes along the top of the window
    background = '#0b0022',

    -- The active tab is the one that has focus in the window
    active_tab = {
      bg_color = '#2b2042',
      fg_color = '#c0c0c0',
      intensity = 'Normal',
      underline = 'None',
      italic = false,
      strikethrough = false,
    },

    -- Inactive tabs are the tabs that do not have focus
    inactive_tab = {
      bg_color = '#1b1032',
      fg_color = '#808080',
    },

    -- You can configure some additional styling when the mouse pointer
    -- moves over inactive tabs
    inactive_tab_hover = {
      bg_color = '#3b3052',
      fg_color = '#909090',
      italic = true,
    },

    -- The new tab button that let you create new tabs
    new_tab = {
      bg_color = '#1b1032',
      fg_color = '#808080',
    },

    -- When hovering over the new tab button
    new_tab_hover = {
      bg_color = '#3b3052',
      fg_color = '#909090',
      italic = true,
    },
  },
}
```

<ParamField path="colors.tab_bar" type="table">
  Configuration for tab bar appearance.
</ParamField>

## Dynamic Color Schemes

You can change color schemes dynamically based on system appearance or time of day:

### 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 'GitHub Light'
  end
end

if wezterm.gui then
  config.color_scheme = scheme_for_appearance(wezterm.gui.get_appearance())
end

return config
```

### Based on Time of Day

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

function scheme_for_time()
  local hour = tonumber(os.date('%H'))
  if hour < 8 or hour >= 20 then
    return 'Tokyo Night'
  else
    return 'GitHub Light'
  end
end

config.color_scheme = scheme_for_time()

return config
```

## Color Transformations

### Foreground Text Adjustments

You can adjust the foreground text colors using HSB (Hue, Saturation, Brightness) transformations:

```lua theme={null}
config.foreground_text_hsb = {
  hue = 1.0,        -- multiplier, 1.0 = no change
  saturation = 1.0, -- multiplier, 1.0 = no change  
  brightness = 1.0, -- multiplier, 1.0 = no change
}
```

<ParamField path="foreground_text_hsb" type="table" default="{hue=1.0, saturation=1.0, brightness=1.0}">
  HSB transformation applied to foreground text colors.
</ParamField>

Example - make text slightly brighter:

```lua theme={null}
config.foreground_text_hsb = {
  hue = 1.0,
  saturation = 1.0,
  brightness = 1.2, -- 20% brighter
}
```

### Bold Text Brightening

<ParamField path="bold_brightens_ansi_colors" type="string" default="BrightAndBold">
  Controls whether bold text is rendered using bright colors. Valid values are:

  * `BrightAndBold`: Use bright colors for bold text
  * `BrightOnly`: Use bright colors but don't render as bold
  * `No`: Don't use bright colors for bold text
</ParamField>

```lua theme={null}
config.bold_brightens_ansi_colors = 'BrightAndBold'
```

## Custom Color Scheme Files

You can define color schemes in separate files and load them:

### Creating a Color Scheme File

Create a file `~/.config/wezterm/colors/mytheme.toml`:

```toml theme={null}
[colors]
foreground = "#d4d4d4"
background = "#1e1e1e"
cursor_bg = "#52ad70"
cursor_border = "#52ad70"
cursor_fg = "#1e1e1e"
selection_bg = "#3a3d41"
selection_fg = "#1e1e1e"

ansi = ["#1e1e1e", "#f48771", "#a1cd5e", "#e4c877", "#6ab0f3", "#f47590", "#00bcd4", "#d4d4d4"]
brights = ["#8b8b8b", "#f48771", "#a1cd5e", "#e4c877", "#6ab0f3", "#f47590", "#00bcd4", "#ffffff"]

[metadata]
name = "My Custom Theme"
author = "Your Name"
```

### Loading Custom Color Schemes

```lua theme={null}
config.color_scheme_dirs = { '~/.config/wezterm/colors' }
config.color_scheme = 'My Custom Theme'
```

<ParamField path="color_scheme_dirs" type="array" default="[]">
  Additional directories to search for color scheme files (TOML format).
</ParamField>

## Quick Select and Copy Mode Colors

Customize colors for WezTerm's quick select and copy mode features:

```lua theme={null}
config.colors = {
  -- Quick select labels (like vim-easymotion)
  quick_select_label_bg = { Color = '#fb4934' },
  quick_select_label_fg = { Color = '#ebdbb2' },
  quick_select_match_bg = { Color = '#b8bb26' },
  quick_select_match_fg = { Color = '#3c3836' },

  -- Copy mode colors
  copy_mode_active_highlight_bg = { Color = '#fabd2f' },
  copy_mode_active_highlight_fg = { Color = '#282828' },
  copy_mode_inactive_highlight_bg = { Color = '#d65d0e' },
  copy_mode_inactive_highlight_fg = { Color = '#ebdbb2' },
}
```

<Warning>
  When setting a `color_scheme`, it will override any values you set in the `colors` table. If you want to customize specific colors while using a base scheme, you need to get the scheme first and modify it.
</Warning>

## Modifying Built-in Color Schemes

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

-- Get the built-in color scheme
local scheme = wezterm.color.get_builtin_schemes()['Dracula']

-- Modify specific colors
scheme.background = '#1a1a1a'
scheme.tab_bar.background = '#1a1a1a'

-- Add it as a custom scheme
config.color_schemes = {
  ['Dracula Modified'] = scheme,
}

config.color_scheme = 'Dracula Modified'

return config
```

## See Also

* [Window Configuration](./window) - Window appearance options
* [Appearance Documentation](/config/appearance) - General appearance configuration
* [Color Scheme Gallery](https://wezfurlong.org/wezterm/colorschemes/index.html) - Browse available schemes