LAYOUTS.md

xfetch Layouts

This document explains how to configure and customize layouts in xfetch.

Built-in Layouts

1. Default Layout (Classic)

The default layout displays the logo (ASCII or image) on the left and the system information modules on the right.

Configuration:

To use this layout, simply omit the layout key in your config or set it to null.

{
    "layout": null,
    // ...
}

2. Side Block Layout

A structured layout where keys and values are displayed in two separate side-by-side boxes.

Configuration:

{
    "layout": "side-block"
}

Appearance:

╭──────────╮ ╭──────────────────────╮
│ User     │ │ jan.rex              │
│ Host     │ │ DIO-LAPTOP           │
╰──────────╯ ╰──────────────────────╯

3. Tree Layout

Displays modules in a hierarchical tree structure. This layout supports grouping modules.

Configuration:

{
    "layout": "tree",
    "modules": [
        {
            "type": "group",
            "title": "OS",
            "modules": ["os", "kernel", "packages"]
        },
        {
            "type": "group",
            "title": "PC",
            "modules": ["cpu", "gpu", "memory"]
        }
    ]
}

Appearance:

 OS
├── os Arch Linux
├── kernel 6.6.1
└── packages 1200 (pacman)
 PC
├── cpu AMD Ryzen 9
└── memory 16 GiB

4. Section Layout

Displays modules in groups with clear section headers.

Configuration:

{
    "layout": "section",
    "modules": [
        {
            "type": "group",
            "title": "Hardware",
            "modules": ["cpu", "gpu", "memory"]
        },
        {
            "type": "group",
            "title": "Software",
            "modules": ["os", "shell"]
        }
    ]
}

Appearance:

────── Hardware ──────
│ cpu: AMD Ryzen 9
│ memory: 16 GiB

────── Software ──────
│ os: Arch Linux

5. Pac-Man Layout

A boxed layout inspired by the Pac-Man game interface.

Configuration:

{
    "layout": "pacman",
    "header_icons": ["ᗧ", "●", "●", "●", "●"], // Icons for top border
    "footer_text": "GAME OVER"                 // Text for bottom border
}

6. Box Layout

Displays the system information enclosed in a simple box with rounded corners.

Configuration:

{
    "layout": "box"
}

7. Line Layout

Displays system information with a horizontal separator line after every 3 modules.

Configuration:

{
    "layout": "line"
}

8. Dots Layout

Similar to the Line layout, but uses dots as separators.

Configuration:

{
    "layout": "dots"
}

9. Bottom Line Layout

A minimal layout that adds a single horizontal line at the very bottom of the information list.

Configuration:

{
    "layout": "bottom_line"
}

10. Section-Box Layout

Like section, but every group is drawn as its own box with a title embedded in the top border. Nested groups render as boxes inside boxes.

Configuration:

{
    "layout": "section-box",
    "modules": [
        { "type": "group", "title": "Hardware", "modules": ["cpu", "gpu"] },
        { "type": "group", "title": "Software", "modules": ["os", "shell"] }
    ]
}

Appearance:

╭─ Hardware ────────────╮
│  Apple M4           │
│ 󰍹 Apple M4           │
╰───────────────────────╯

╭─ Software ────────────╮
│  Darwin 26.5.2       │
╰───────────────────────╯

11. Custom-X Layout

The most flexible layout: every border line is a literal template written in the custom_x config object, with {fill} and {title} placeholders, configurable width, internal dividers and per-module boxes. See CUSTOM_X.md for the full reference.

Configuration:

{
    "layout": "custom-x",
    "custom_x": {
        "top": "╔═══════ XFETCH ═══════{fill}╗",
        "bottom": "╚══════════════════════{fill}╝",
        "left": "║",
        "right": "║",
        "fill": "═",
        "padding": 1,
        "width": "full",
        "group_title": "╭─── {title} ───{fill}╮"
    },
    "modules": [
        { "type": "group", "title": "Hardware", "modules": ["cpu", "gpu"] }
    ]
}

12. Compact Layout

Icon-to-value layout without row keys: every module renders as icon value on a single line. Use show_keys or the labels map in other layouts when you need the keys back.

Configuration:

{
    "layout": "compact"
}

Appearance:

 Arch Linux x86_64
 6.6.87.2-arch1-1
 16 GiB / 32 GiB (50%)

13. Minimal Layout

Plain text output with no logo, borders or icons: one key: value line per module (a module whose labels entry is empty prints only its value). key_width still pads the keys so the values align, and group titles render as -- Title -- separators.

Configuration:

{
    "layout": "minimal",
    "key_width": 10
}

Appearance:

os:        Arch Linux x86_64
kernel:    6.6.87.2-arch1-1
memory:    16 GiB / 32 GiB (50%)

14. Horizontal Layout

Stacks the logo above the module list instead of side by side. The content is rendered exactly like the classic layout; only the placement changes.

Configuration:

{
    "layout": "horizontal"
}

15. Bottom Layout

Like horizontal, but the logo is printed below the module list (useful when the terminal scrolls the fetch out of view).

Configuration:

{
    "layout": "bottom"
}

Module Grouping

For tree and section layouts, you can define groups in the modules list:

"modules": [
    // Simple module
    "uptime",
    
    // Group
    {
        "type": "group",
        "title": "Group Title",
        "modules": [
            "os",
            "kernel"
            // You can nest groups too!
        ]
    }
]

Available Modules

• os: Operating System
• kernel: Kernel version
• hostname: Hostname
• user: Current username
• datetime: Current date and time
• uptime: System uptime
• packages: Package count
• shell: Current shell
• terminal: Current terminal emulator
• wm: Window Manager / Desktop Environment
• cpu: CPU information
• gpu: GPU information
• memory: RAM usage
• swap: Swap usage
• disk: Disk usage
• battery: Battery status
• local_ip: Local IP address
• palette: Color palette

Icons

We recommend using Nerd Fonts for icons to ensure they render correctly. You can customize icons in the icons section of your config file.

"icons": {
    "os": "",
    "cpu": "",
    // ...
}