# How to Configure File Preview with Syntax Highlighting in Superfile: Chroma vs bat

> Configure Superfile file previews with syntax highlighting. Choose between built-in Chroma or external bat for enhanced code readability. Learn how to set your preference in config.toml.

- Repository: [Yorukot/superfile](https://github.com/yorukot/superfile)
- Tags: how-to-guide
- Published: 2026-07-30

---

**Set `code_previewer = ""` (empty string) in `~/.config/superfile/config.toml` to use the built-in Chroma library, or set `code_previewer = "bat"` to delegate syntax highlighting to the external `bat` command-line tool.**

Superfile, the modern terminal file manager from the yorukot/superfile repository, provides a split-pane preview feature that renders source code with syntax highlighting. You can configure which rendering engine handles this highlighting by modifying a single configuration field, choosing between the integrated **Chroma** library or the external **bat** tool based on your theming preferences and environment.

## Configuration Options

Superfile selects its highlighting engine based on the `code_previewer` field defined in the configuration struct at [`src/internal/common/config_type.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go). This setting accepts specific string values that determine whether to use internal or external rendering.

### Built-in Chroma Highlighter (Default)

When `code_previewer = ""` (empty string or omitted), Superfile uses its internal highlighter powered by the `github.com/alecthomas/chroma/v2` library. This requires no external dependencies and works immediately after installation.

### External bat Tool

When `code_previewer = "bat"`, Superfile delegates highlighting to the `bat` program. This option provides the same color schemes and file-type detection available in standalone `bat`, but requires installing `bat` and ensuring it exists in your system `$PATH`.

## Implementation Details

The selection logic resides in [`src/internal/ui/preview/render.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/preview/render.go), where Superfile checks the configuration value at runtime:

```go
if common.Config.CodePreviewer == "bat" {
    // Try to run `bat` – if it fails, show an informative message
    if !batInstalled {
        return r.AddLines(common.FilePreviewBatNotInstalledText).Render()
    }
    // …invoke bat and pipe its output…
} else {
    // Fallback to Chroma via ansichroma
    fileContent, err = ansichroma.HightlightString(
        fileContent, format.Config().Name, /* style options */)
}

```

When `bat` is selected but not found, the UI displays the `FilePreviewBatNotInstalledText` message rather than failing silently. Additional terminal capability utilities used by the preview system are provided in [`src/pkg/file_preview/utils.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/utils.go).

## Step-by-Step Configuration Guide

Follow these steps to switch between rendering engines:

1. **Open the configuration file** at `~/.config/superfile/config.toml` (default location).

2. **Set the `code_previewer` value** under the `[default]` section:

   For Chroma (built-in):
   ```toml
   [default]
   code_previewer = ""
   ```

   For bat (external):
   ```toml
   [default]
   code_previewer = "bat"
   ```

3. **Install bat (if required)**:

   ```bash
   # macOS (Homebrew)

   brew install bat

   # Debian/Ubuntu

   sudo apt-get install bat

   # Arch Linux

   sudo pacman -S bat
   ```

4. **Restart Superfile** to apply the configuration changes.

5. **Verify** by opening a source code file in the preview panel. The syntax colors should now reflect your selected engine's theme.

## Key Source Files

| File | Purpose |
|------|---------|
| [`src/internal/common/config_type.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go) | Defines the `CodePreviewer` configuration field and accepted values. |
| [`src/internal/ui/preview/render.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/preview/render.go) | Contains runtime logic that switches between Chroma and `bat` based on configuration. |
| [`src/pkg/file_preview/utils.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/utils.go) | Provides helper utilities for terminal capabilities used by the preview renderer. |

## Summary

- **Chroma** (`code_previewer = ""`): Uses the internal `github.com/alecthomas/chroma/v2` library via the `ansichroma` wrapper; requires no external setup.
- **bat** (`code_previewer = "bat"`): Delegates to external `bat` binary; requires installation and `$PATH` availability, but provides consistent theming with your `bat` configuration.
- Configuration changes take effect immediately after restarting Superfile.
- Missing `bat` binaries trigger a graceful error message in the preview panel rather than a crash.

## Frequently Asked Questions

### What happens if I configure `code_previewer = "bat"` without installing bat?

Superfile detects the missing binary and displays a "bat not installed" message in the preview panel. This check occurs in [`src/internal/ui/preview/render.go`](https://github.com/yorukot/superfile/blob/main/src/internal/ui/preview/render.go) before attempting execution, preventing crashes and informing you of the missing dependency.

### Can I customize themes when using the built-in Chroma option?

The built-in renderer passes style options through the `ansichroma.HightlightString` function. While Superfile provides sensible defaults, customizing themes currently requires modifying the parameters passed to this function in the source code, as the TOML configuration does not expose Chroma style options directly.

### Does the bat option support all file types that standalone bat recognizes?

Yes. When `code_previewer = "bat"` is set, Superfile pipes file contents through the `bat` command, inheriting `bat`'s automatic language detection and syntax definitions. Any language recognized by your installed `bat` version will render correctly in the preview pane.

### Where is the configuration file located on Windows?

On Windows, Superfile looks for [`config.toml`](https://github.com/yorukot/superfile/blob/main/config.toml) in `%APPDATA%\superfile\` or `%LOCALAPPDATA%\superfile\` depending on the build. The `code_previewer` setting functions identically across all supported platforms.