How to Customize fzf's Color Scheme with the --color Option

Use the --color flag to select base themes like dark or light, or specify individual UI elements with comma-separated key:value pairs to override specific colors and text attributes.

The junegunn/fzf command-line fuzzy finder implements a flexible theming system centered on the ColorTheme struct defined in src/tui/tui.go. You can customize fzf's color scheme with the --color option by either selecting predefined base themes or fine-tuning individual interface components through a declarative key-value syntax parsed in src/options.go.

How fzf Parses the --color Option

Inside src/options.go, the parseTheme function processes the --color argument. This parser supports two distinct modes: base theme selection and granular component customization.

Base Theme Selection

When you pass dark, light, base16 (or 16), or bw (or no), parseTheme swaps the entire theme for predefined constants like tui.Dark256, tui.Light256, or tui.NoColorTheme.

Component-Level Parsing

For custom specifications, the parser splits the string on commas or whitespace into key:value tokens. The key (e.g., bg, fg, preview-border) maps to a field in the ColorTheme struct, while the remaining components define colors and attributes.

Using Built-in Base Themes

The fastest way to customize fzf's appearance is selecting a base theme.

fzf --color=dark        # Dark 256-color theme (default)

fzf --color=light       # Light 256-color theme

fzf --color=base16      # 16-color theme for limited terminals

fzf --color=bw          # Monochrome, no color

Customizing Individual UI Elements

For precise control, override specific interface components using key:value pairs.

Available Color Keys

The ColorTheme struct in src/tui/tui.go defines the following configurable elements:

• bg – Background of the interface
• fg – Default foreground text
• hl – Matched substring highlight
• hl+ – Matched substring when line is selected
• info – Info line (e.g., "N/M selected")
• border – UI border
• prompt – Prompt symbol
• pointer – Pointer to current line
• marker – Multi-select marker
• spinner – Loading indicator
• header – Header line
• preview-border, preview-bg – Preview window elements

Supported Color Formats

The parser in src/options.go accepts three color specification types:

• Named ANSI colors: red, green, bright-blue, etc.
• Hex values: #rrggbb (converted via tui.HexToColor in src/tui/tui.go)
• Decimal values: Integers from -1 to 255 for ANSI/256-color codes

Text Attributes

Append attributes to colors using colons:

• regular, bold, dim, italic
• underline, underline-double
• blink, reverse, strikethrough

Example syntax: prompt:bold,cyan or fg:#c5c8c6:italic.

Practical Examples

Override multiple elements at once:

fzf --color='bg:#1e1e1e,fg:#c5c8c6,hl:magenta,hl+:#ff79c6,info:yellow,border:#44475a'

Combine base themes with specific overrides:

fzf \
  --color=dark \
  --color='prompt:green,border:bright-blue' \
  --color='preview-bg:#282a36,preview-border:#ff79c6'

Disable colors completely:

fzf --color=''   # Clears theme to tui.EmptyTheme

# or

fzf --color=bw     # Uses tui.NoColorTheme

Summary

• The --color option controls the ColorTheme struct defined in src/tui/tui.go, parsed by parseTheme in src/options.go.
• Base themes: Use dark, light, base16, or bw for instant theme switching.
• Custom colors: Specify key:value pairs for UI elements like bg, fg, hl, and border, supporting hex codes, ANSI names, and attributes like bold or italic.
• Multiple flags: Layer several --color arguments to merge base themes with specific overrides.
• Disable colors: Pass an empty string --color='' or use bw to remove all coloring.

Frequently Asked Questions

What are all the available color keys in fzf?

The ColorTheme struct in src/tui/tui.go defines keys including bg (background), fg (foreground), hl (highlight), hl+ (current line highlight), info, border, prompt, pointer, marker, spinner, header, and preview-specific keys like preview-border and preview-bg.

Can I use hex color codes with fzf --color?

Yes. The parser in src/options.go supports hex strings in the format #rrggbb, which are converted to terminal colors via the tui.HexToColor function in src/tui/tui.go. For example: fzf --color='bg:#282c34,fg:#abb2bf'.

How do I make fzf completely monochrome?

Pass an empty string to the color option (fzf --color='') or use the bw base theme (fzf --color=bw). Both methods set the theme to tui.EmptyTheme or tui.NoColorTheme, effectively disabling all color output and using only default terminal foreground and background colors.

Why do multiple --color flags merge instead of replace?

The parseTheme function in src/options.go modifies the existing ColorTheme struct incrementally when processing custom key-value pairs. When you specify multiple --color arguments, each subsequent call updates the theme without clearing previous values, allowing you to layer a base theme with specific component overrides.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}