# How to Enable and Configure Image Preview Using Sixel in Superfile

> Learn to enable and configure image preview in Superfile. Superfile offers Kitty protocol or ANSI block rendering for image display.

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

---

**Sixel image preview is referenced in the Superfile codebase but is not yet implemented; to view images today, enable `show_image_preview` in [`config.toml`](https://github.com/yorukot/superfile/blob/main/config.toml) and Superfile will automatically select the Kitty protocol or fall back to ANSI block rendering.**

Superfile is a terminal-based file manager designed to render image previews directly inside the console. While the repository contains hooks for Sixel—the legacy DEC graphics standard—the feature remains incomplete in current builds. Understanding how to enable and configure image preview using Sixel in superfile requires examining the protocol detection logic, the configuration struct, and the actual rendering pipeline implemented in the Go source.

## Current Sixel Implementation Status

The Superfile codebase acknowledges Sixel as a potential rendering target, but the actual graphics pipeline is missing. In [`src/config/icon/icon.go`](https://github.com/yorukot/superfile/blob/main/src/config/icon/icon.go), you will find a `sixel` entry mapped to the generic `"image"` icon type, indicating the protocol is cataloged for future support.

However, inspection of [`src/pkg/file_preview/image_preview.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/image_preview.go) reveals that the `ImagePreviewer` struct only implements two rendering paths:

1.  **Kitty graphics protocol** – Full-pixel, transparent rendering for compatible terminals
2.  **ANSI fallback** – Coarse representation using colored Unicode blocks

There is no `renderSixel()` function or Sixel-specific encoding logic in the current source, meaning terminals advertising Sixel capability via `$TERM` or `$TERM_PROGRAM` will not trigger a Sixel render.

## Enabling Image Previews via Configuration

Despite the incomplete Sixel support, you can activate the image preview feature to utilize the working protocols. The toggle is controlled by the `ShowImagePreview` boolean field defined in [`src/internal/common/config_type.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go).

To enable previews, modify your configuration file:

```toml

# src/superfile_config/config.toml

# Enable image preview for any supported protocol (Kitty, ANSI, future Sixel)

show_image_preview = true

```

The configuration struct binds this value as follows:

```go
// src/internal/common/config_type.go
type Config struct {
    ShowImagePreview bool `toml:"show_image_preview" comment:"\nWhether to show image preview."`
}

```

When this flag is set to `true`, Superfile enters the preview pipeline on file selection. When future versions implement the Sixel renderer, this same configuration flag will activate it automatically on compatible terminals without requiring changes to your configuration file.

## Protocol Selection and Terminal Detection

Superfile determines which rendering engine to use by inspecting environment variables and terminal capabilities. The selection hierarchy implemented in [`src/pkg/file_preview/image_preview.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/image_preview.go) follows this logic:

- **Kitty detection** – Checks for Kitty-specific environment variables and terminal responses
- **Sixel detection** – Recognizes the capability string but currently skips to fallback (see the `isSixelSupported()` placeholder logic)
- **ANSI fallback** – Default pathway when no graphics protocol is available

The simplified rendering dispatch looks like this:

```go
// src/pkg/file_preview/image_preview.go (simplified)
func (p *ImagePreviewer) Render(ctx Context) error {
    if p.isKittySupported() {
        return p.renderKitty(ctx)   // Full‑color preview
    }
    // No Kitty → fall back to ANSI blocks (Sixel not yet available)
    return p.renderANSI(ctx)
}

```

Superfile reads `$TERM` and `$TERM_PROGRAM` during initialization to populate these capability checks.

## Testing the ANSI Fallback

If you want to observe how Superfile behaves when neither Kitty nor Sixel is available—effectively previewing the current fallback behavior—you can force the ANSI renderer by launching Superfile in a generic terminal environment:

```bash

# Example: run Superfile in a plain xterm that lacks Kitty protocol

export TERM=xterm
superfile

```

This is useful for testing the configuration activation (`show_image_preview = true`) on systems where you cannot install a Kitty-compatible terminal emulator.

## Summary

- **Sixel is recognized but unimplemented**: The `sixel` string exists in [`src/config/icon/icon.go`](https://github.com/yorukot/superfile/blob/main/src/config/icon/icon.go), but [`src/pkg/file_preview/image_preview.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/image_preview.go) lacks a corresponding renderer.
- **Enable previews with one flag**: Set `show_image_preview = true` in [`src/superfile_config/config.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/config.toml) to activate the preview pipeline.
- **Automatic protocol selection**: Superfile prioritizes the Kitty graphics protocol and degrades gracefully to ANSI Unicode blocks when necessary.
- **Future-proof configuration**: When Sixel support ships, it will activate automatically under the existing `ShowImagePreview` configuration on terminals advertising the capability.

## Frequently Asked Questions

### Is Sixel image preview currently working in Superfile?

No. While the codebase contains a `sixel` entry in the icon map at [`src/config/icon/icon.go`](https://github.com/yorukot/superfile/blob/main/src/config/icon/icon.go) and recognizes the capability string during terminal detection, the actual rendering implementation in [`src/pkg/file_preview/image_preview.go`](https://github.com/yorukot/superfile/blob/main/src/pkg/file_preview/image_preview.go) has not been written. Superfile currently only renders images using the Kitty graphics protocol or ANSI Unicode blocks.

### How do I enable image previews in Superfile right now?

Edit your [`src/superfile_config/config.toml`](https://github.com/yorukot/superfile/blob/main/src/superfile_config/config.toml) file and set `show_image_preview = true`. This boolean field, defined in [`src/internal/common/config_type.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go), activates the preview pipeline. Superfile will then automatically negotiate with your terminal to use the best available rendering method.

### What happens if my terminal doesn't support the Kitty protocol?

Superfile detects terminal capabilities via environment variables such as `$TERM` and `$TERM_PROGRAM`. If Kitty graphics are unavailable, it automatically falls back to an ANSI-based preview that uses colored Unicode blocks to approximate the image content, as implemented in the `renderANSI` method.

### Will the same configuration work when Sixel support is added?

Yes. According to the `Config` struct definition in [`src/internal/common/config_type.go`](https://github.com/yorukot/superfile/blob/main/src/internal/common/config_type.go), the `ShowImagePreview` flag is protocol-agnostic. When Sixel rendering is eventually implemented, it will activate automatically on terminals advertising Sixel capability when this flag is set to `true`, without requiring additional configuration changes.