Zsh: Partial Colouring Completion with Preserved unmatched parts of LS_COLORS

To achieve partial colouring in Zsh completion while preserving unmatched parts of LS_COLORS, you must use the zstyle command to configure the completion:default style with color and list-colors. This approach leverages Zsh’s built-in completion engine to apply file system colours only to matched components, ensuring that uncompleted text remains in its default terminal colour rather than being overwritten or lost.

The Problem with Standard Completion Colouring

By default, Zsh does not colour completion lists unless explicitly configured. When users enable completion colouring using standard methods, they often encounter a side effect: the entire line is treated as a single unit for styling purposes. If you simply enable global colouring, the unmatched portion of your filename—the part you have not yet typed—might disappear from view or adopt an unexpected colour scheme because the completion widget replaces the visual representation of the buffer. This issue is particularly frustrating when working with long paths where only the final directory name is ambiguous. You want the completed suffix to be highlighted according to your LS_COLORS definitions (e.g., green for directories, blue for symlinks), but you want the prefix you have already typed to remain visible and uncoloured, or at least coloured consistently with the rest of your prompt. The challenge lies in decoupling the visual treatment of the matched completion from the unmatched input. Standard shell configurations often rely on external tools like ls for colour output, which do not integrate directly with the Zsh Line Editor (ZLE). Therefore, relying on environment variables alone is insufficient. We need a configuration that tells Zsh specifically how to parse the completion list and assign colours based on file type, while respecting the existing state of the user's input.

Configuring List Colours via Zstyle

The core solution involves the zstyle builtin, which manages styles for various Zsh features. To control how completions are displayed, we target the completion:default group. The key style here is list-colors. This style accepts a string that defines regular expressions mapping file attributes to terminal escape codes. You can set this by adding the following line to your ~/.zshrc:

zstyle ':completion:*' list-colors ${(s.:.)LS_COLORS}

This command parses the existing LS_COLORS environment variable and converts it into a format that Zsh’s completion engine understands. The ${(s.:.)LS_COLORS} expansion splits the colon-separated values of LS_COLORS into an array, which list-colors then consumes. This ensures that the colours used in completion match exactly what you see in ls output. However, this alone might still affect the entire line if other styles interfere. To ensure that only the completed part is coloured, we must also ensure that the color style is enabled for the default completion context. Add this line as well:

zstyle ':completion:*' color on

This combination allows Zsh to apply colours to the completion candidates without altering the visual structure of the unmatched text. The unmatched text remains in the buffer as plain text, while the suggested matches are rendered with their respective file-type colours.

Preserving Unmatched Text Visibility

A common concern is whether enabling colouring will hide the unmatched characters. It will not, provided you do not enable aggressive menu selection modes that overwrite the prompt. The list-colors style operates on the list of possible completions displayed below the current line. It does not modify the actual content of the editing buffer until you accept a completion. If you find that the unmatched text appears dim or invisible, check your terminal theme settings. Some themes define specific foreground colours for the cursor or the current line that might conflict with the completion colouring. In such cases, you may need to adjust your terminal emulator’s colour palette or modify the LISTPROMPT style in Zsh. Additionally, ensure that you are not using older versions of Zsh that have bugs in the completion colouring subsystem. Zsh 5.0 and above handle list-colors robustly. If you are on an older version, consider upgrading or using the compinit initialization properly to ensure all styles are loaded correctly. For more details on managing completion behaviors, such as preventing ambiguous completions, you might find Configuring Zsh Completion: Prevent Ambiguous Completions and Show Menu useful. This article discusses how to fine-tune the display logic, which complements our colouring setup.

Troubleshooting Common Issues

Even with correct configuration, issues may arise due to conflicting plugins or custom widgets. Many popular frameworks like Oh My Zsh load completion scripts early in the startup process. If these scripts redefine list-colors after your zstyle commands, your settings will be overridden. To fix this, place your zstyle lines after the source command for any completion frameworks, or better yet, in a separate file sourced at the end of .zshrc. Another potential issue is the interaction with setopt options. Ensure that KSH_AUTOLOAD is not interfering with function loading, although this rarely affects colouring directly. More commonly, the NO_BEEP option might mask visual feedback, making it seem like colouring has failed if the completion list is empty. If you are migrating from Bash, you might notice differences in how colours are handled. Bash relies heavily on PROMPT_COMMAND and external scripts, whereas Zsh integrates colouring natively into the completion engine. For insights into compatibility challenges between shells, refer to Troubleshooting Compatibility. It is also important to understand the order in which your shell sources files. If your LS_COLORS variable is set after Zsh initializes completion, the list-colors style will capture an empty or outdated value. Ensure that LS_COLORS is exported before compinit runs. Understanding this sequence is crucial, as detailed in Understanding the Order of Shell Source Files.

Advanced Customization

For users who require granular control, list-colors supports regex patterns beyond simple file types. You can define custom colours for specific filenames or extensions. For example, to highlight files ending in .log in red, you could add a specific entry to your list-colors string. However, modifying LS_COLORS directly is usually sufficient for most use cases. Remember that LS_COLORS itself can be customized using the dircolors command. By generating a new LS_COLORS string from a custom dircolors database, you indirectly control completion colours. This method provides a unified colour scheme across your terminal, ls output, and Zsh completions. Finally, always test your changes in a non-production shell instance. Use zsh -f to start a minimal Zsh session, source your .zshrc, and verify that the completion colours appear as expected. This isolates the issue from any complex plugin architectures or third-party configurations that might be interfering with the basic completion engine.

Frequently Asked Questions

Why do my completion colours disappear when I press Tab?

This usually happens if the color style is not enabled for the completion context. Ensure you have run zstyle ':completion:*' color on in your configuration. Additionally, check if a plugin is overriding this setting after your initial configuration loads.

Can I use different colours for completion than for ls output?

Yes, you can manually construct a list-colors string that differs from LS_COLORS. Instead of parsing LS_COLORS, you can provide a hardcoded string of colour codes to zstyle, allowing you to create a distinct visual scheme for completions.

Does this work with fish shell or bash?

No, the zstyle command and list-colors style are specific to Zsh. Other shells like Bash and Fish have their own mechanisms for completion colouring, which are not compatible with Zsh’s configuration syntax.

What if LS_COLORS is not set in my environment?

If LS_COLORS is unset, the list-colors style will fail to apply any colours. You should set LS_COLORS using dircolors or ensure your terminal profile exports it. Without this variable, Zsh has no reference for file-type colours.

How do I reset completion colours to default?

You can reset the style by running zstyle ':completion:*' list-colors '' and zstyle ':completion:*' color off. This removes any custom colouring and reverts to the standard terminal appearance for completion lists.