This document covers the presentation layer of fastfetch, which transforms detected system information into formatted output for terminal display or JSON export. The presentation system includes:
For information about logo rendering and positioning, see Logo Rendering System. For module-specific output customization, see Output Formatting and Display Options. For detailed format string syntax, see Format String System.
Sources: src/options/display.h35-94 src/common/format.c123-413 src/common/percent.c56-220 src/common/temps.c6-65
The presentation pipeline processes module output through a formatting layer before generating terminal text or JSON output. Each formatter function reads from the global instance.config.display (FFOptionsDisplay) to apply consistent styling across all modules.
Sources: src/options/display.h35-94 src/common/format.c123-413 src/common/percent.c56-220 src/common/temps.c6-65
The presentation pipeline consists of four layers:
The FFOptionsDisplay structure centralizes all presentation configuration, controlling how module output is formatted and displayed.
Sources: src/options/display.h35-94 src/options/display.h6-33
Display options are loaded in priority order (highest to lowest):
| Priority | Source | Parser Function | File Reference |
|---|---|---|---|
| 1 | Command Line Args | ffOptionsParseDisplayCommandLine() | src/options/display.c528-847 |
| 2 | JSON/JSONC Config | ffOptionsParseDisplayJsonConfig() | src/options/display.c10-516 |
| 3 | Compiled Defaults | ffOptionsInitDisplay() | src/options/display.c849-917 |
Command-line arguments override config file settings, which override defaults. This allows users to set persistent preferences in config files while temporarily overriding specific values via CLI.
JSON Configuration Example:
Sources: doc/json_schema.json451-933 src/options/display.c10-916 src/data/help.json451-933
The color parser (ffOptionParseColor() in src/common/color.c) converts color strings to ANSI escape sequence codes stored in FFstrbuf fields. Supported formats:
black, red, green, yellow, blue, magenta, cyan, whitebright_, light_, dim_, italic_, underline_, blink_, inverse_, hidden_, strike_#RRGGBB hex format (converted to 24-bit ANSI codes)default (terminal default), reset_ (clear all formatting)Color Application Flow:
When pipe mode is enabled (detected via isatty(1) or forced with --pipe), all ANSI code generation is skipped to produce plain text output suitable for piping or redirection.
Sources: src/common/color.h src/common/color.c src/options/display.c50-74 doc/json_schema.json4-19
The format string system provides a powerful template engine for customizing module output. Each module's format option accepts a template with placeholders that are replaced with actual values.
Sources: src/common/format.c123-413 src/common/format.h
The format string engine supports multiple placeholder types:
| Syntax | Description | Example |
|---|---|---|
{} | Auto-increment argument | "{} cores" → first arg |
{1} | Positional argument (1-indexed) | "{1} MHz" → first arg |
{name} | Named argument | "{cores-logical} cores" |
{:width} | Truncate to width, trim right | "{name:20}" |
{<width} | Pad right to width | "{name<15}" |
{>width} | Pad left to width | "{value>10}" |
{~start} | Substring from start | "{name~5}" |
{~start,end} | Substring range | "{name~0,10}" |
{?arg}...{?} | Conditional if arg set | "{?temp}Temp: {temp}{?}" |
{/arg}...{/} | Conditional if arg NOT set | "{/temp}No temp data{/}" |
{#color} | Set color | "{#red}Error{#}" |
{#} | Reset color | "{#red}Text{#} Normal" |
{$var} | Environment variable | "{$HOME}" |
{$1} | Constant (from config) | "{$1}" → first constant |
{-} | Stop processing | "Only this{-} not this" |
Sources: src/common/format.c123-413 tests/format.c1-141 doc/json_schema.json276-516
Arguments passed to the format engine are typed using FFformatarg:
Sources: src/common/format.h src/common/format.c9-59
Sources: src/common/percent.h7-24 src/options/display.h77-83
The percentType field uses bitflags to control display behavior:
| Flag | Value | Description |
|---|---|---|
FF_PERCENTAGE_TYPE_NUM_BIT | 1 | Show percentage number |
FF_PERCENTAGE_TYPE_BAR_BIT | 2 | Show percentage bar |
FF_PERCENTAGE_TYPE_HIDE_OTHERS_BIT | 4 | Hide other output when showing percentage |
FF_PERCENTAGE_TYPE_NUM_COLOR_BIT | 8 | Color the percentage number |
FF_PERCENTAGE_TYPE_BAR_MONOCHROME_BIT | 16 | Use single color for bar |
Common combinations:
1 (0b00001) = Number only, no color2 (0b00010) = Bar only3 (0b00011) = Number + Bar9 (0b01001) = Number with color (default)10 (0b01010) = Bar monochromeSources: src/common/percent.h7-16 doc/json_schema.json42-70
Sources: src/common/percent.c169-220
Color Threshold Logic:
For threshold configuration with green <= yellow (e.g., green=30, yellow=60):
[0%, green) → Green color[green, yellow) → Yellow color[yellow, 100%] → Red colorFor threshold configuration with green > yellow (e.g., green=70, yellow=40):
[0%, yellow) → Red color[yellow, green) → Yellow color[green, 100%] → Green colorThis allows both "low is good" (disk usage) and "high is good" (battery level) semantics.
Sources: src/common/percent.c169-220 src/common/percent.h26-34
The borderAsValue mode (lines 63-64) is activated when both barBorderLeftElapsed and barBorderRightElapsed are configured. In this mode, borders scale with percentage: the first/last character of the bar uses the elapsed border character at position 0 or width-1.
Sources: src/common/percent.c56-167
Bar Component Configuration:
| Component | Config Field | Default | Description |
|---|---|---|---|
| Elapsed character | barCharElapsed | "â– " | Character for completed portion |
| Total character | barCharTotal | "-" | Character for remaining portion |
| Left border | barBorderLeft | "[ " | Left edge of bar |
| Right border | barBorderRight | " ]" | Right edge of bar |
| Width | barWidth | 10 | Number of character cells |
| Elapsed color | barColorElapsed | "auto" | Color for completed (auto = threshold-based) |
| Total color | barColorTotal | "light_white" | Color for remaining |
| Border color | barColorBorder | "light_white" | Color for borders |
Alternative Border Mode: If both barBorderLeftElapsed and barBorderRightElapsed are set, borders become part of the bar content and scale with percentage.
Sources: src/common/percent.c56-167 src/options/display.h67-76
The bar can use two coloring strategies:
Monochrome Mode (FF_PERCENTAGE_TYPE_BAR_MONOCHROME_BIT set):
Gradient Mode (default):
Gradient Color Transition Implementation:
At each block index i, the code checks if i crosses a section boundary (calculated as (threshold / 100.0 * barWidth + 0.5)). When crossing from green→yellow or yellow→red thresholds, the code emits a new \e<FileRef file-url="https://github.com/fastfetch-cli/fastfetch/blob/f0759acd/%sm ANSI code with the appropriate color from percentColorGreen/Yellow/Red. This creates smooth visual transitions where bar color changes mid-bar.\n\nThe monochrome path (lines 101-119) applies a single color based on the overall percentage's threshold position, avoiding per-block color calculations.\n\nSources#LNaN-LNaN" NaN file-path="%smANSI code with the appropriate color frompercentColorGreen/Yellow/Red`. This creates smooth visual transitions where bar color changes mid-bar.\n\nThe monochrome path (lines 101-119) applies a single color based on the overall percentage's threshold position, avoiding per-block color calculations.\n\nSources">Hii
The temperature formatter provides color-coded temperature output with unit conversion support.
Sources: src/options/display.h13-19 src/options/display.h61-66 src/common/option.h
Sources: src/common/temps.c6-65
The system accepts temperatures in Celsius and converts to the configured unit:
| Unit | Conversion Formula | Default Space | Symbol |
|---|---|---|---|
| Celsius | value | No | °C |
| Fahrenheit | value × 1.8 + 32 | No | °F |
| Kelvin | value + 273.15 | Yes | K |
Configuration:
tempUnit - Select output unittempNdigits - Decimal places (default: 2)tempSpaceBeforeUnit - Space before symbol (default: unit-dependent)Sources: src/common/temps.c40-55 src/options/display.h61-66
Like percentages, temperatures support bidirectional threshold logic:
Standard Mode (green <= yellow, e.g., 45°C, 70°C):
Inverted Mode (green > yellow):
This allows expressing both "low is good" and "high is good" thermal semantics.
Sources: src/common/temps.c18-37 doc/json_schema.json94-119
Fastfetch supports two primary output modes: formatted text for terminal display and structured JSON for programmatic consumption.
Module print functions call ffPrintLogoAndKey() (defined in src/common/printing.h) which handles key formatting and separator output. The value portion is built by the module using format strings and specialized formatters, then written via ffWriteFDBuffer() which wraps the platform-specific write syscall.
Sources: src/common/printing.h src/common/printing.c src/options/display.c
Text Output Features:
isatty())Key Width Alignment:
When keyWidth is set, keys are padded to a consistent width:
CPU: Intel Core i7-9700K GPU: NVIDIA GeForce RTX 2060 Memory: 16 GB Sources: src/options/display.c437-466 src/data/help.json547-590
When instance.state.resultDoc is non-NULL (set by --format json or --json), each module calls its JSON generator instead of its print function. The generators add properties to a shared yyjson_mut_doc which is serialized once after all modules execute. This produces a single JSON object with all module results as top-level keys.
Example JSON generators:
ffGenerateCPUJsonResult() in CPU moduleffGenerateGPUJsonResult() in GPU moduleffGenerateMemoryJsonResult() in Memory moduleSources: Module-specific ffGenerate*JsonResult() functions, src/fastfetch.c
JSON Output Format:
When --format json or -j is specified, fastfetch outputs structured JSON instead of formatted text:
Activation:
--format json or --json / -j"format": "json" in JSONCJSON Mode Characteristics:
Sources: src/data/help.json56-77 src/fastfetch.c
| Feature | Text Mode | JSON Mode |
|---|---|---|
| Purpose | Human-readable terminal display | Machine-readable data export |
| Colors | Yes (ANSI escape codes) | No |
| Formatting | Custom format strings, bars, icons | Raw structured data |
| Modules | Only configured modules | All detected data |
| Logo | Yes | No |
| Streaming | Line-by-line | Complete document |
| Customization | High (colors, layout, format) | None (standard JSON) |
Sources: src/fastfetch.c src/options/display.c
In addition to the core formatting systems, fastfetch provides specialized formatters for common value types.
Binary sizes (bytes, memory, disk space) use ffStrbufAppendFileSize() with configurable binary prefixes:
| Prefix Type | 1024 Multiplier | Symbol | Example |
|---|---|---|---|
| IEC (default) | Yes | KiB, MiB, GiB | 16.5 GiB |
| SI | No (1000) | kB, MB, GB | 17.7 GB |
| JEDEC | Yes | KB, MB, GB | 16.5 GB |
Configuration:
sizeBinaryPrefix - Prefix systemsizeNdigits - Decimal placessizeMaxPrefix - Maximum prefix (B, kB, MB, GB, TB, PB, EB, ZB, YB)sizeSpaceBeforeUnit - Spacing controlSources: src/options/display.h6-11 src/options/display.c99-162 src/util/stringUtils.h
CPU/GPU frequencies use specialized formatting:
Configuration:
freqNdigits - Decimal places (default: 2)freqSpaceBeforeUnit - Space before "GHz" (default: module-dependent)Output: 3.60 GHz or 3600 MHz depending on magnitude
Sources: src/options/display.c476-510 src/data/help.json832-850
Time durations (uptime, battery time) support abbreviated and full formats:
Full Format: "2 hours, 34 mins" Abbreviated: "2h 34m"
Configuration:
durationAbbreviation - Use short formatdurationSpaceBeforeUnit - Space before unitSources: src/options/display.c77-98 src/data/help.json525-545
General floating-point numbers:
Configuration:
fractionNdigits - Decimal places (-1 = auto)fractionTrailingZeros - Keep trailing zeros (default/always/never)Sources: src/options/display.c394-434 src/data/help.json851-871
Each module integrates with the presentation system through standardized interfaces.
Sources: Module-specific print functions, src/detection/displayserver/displayserver.c
Each module defines named placeholders for its format string:
Example - CPU Module:
Users can then use these placeholders in custom format strings:
Sources: doc/json_schema.json320-323 module print functions
Each module can override global display settings:
| Option | Config Field | Description |
|---|---|---|
| Key | key | Module label text |
| Key Color | keyColor | Override global key color |
| Key Width | keyWidth | Override global key width |
| Output Color | outputColor | Override global output color |
| Format | format | Custom format string |
| Percentage Config | percent | Module-specific thresholds |
| Temperature Config | temp | Module-specific thresholds |
Sources: doc/json_schema.json20-41 src/common/option.h
| Structure | Location | Purpose |
|---|---|---|
FFOptionsDisplay | src/options/display.h35-94 | Global display configuration |
FFPercentageModuleConfig | src/common/percent.h19-24 | Percentage display settings |
FFColorRangeConfig | src/common/option.h | Temperature threshold settings |
FFModuleArgs | src/common/option.h | Per-module display overrides |
| Function | Location | Purpose |
|---|---|---|
ffParseFormatString() | src/common/format.c123-413 | Template engine main function |
ffPercentAppendBar() | src/common/percent.c56-167 | Render percentage bar |
ffPercentAppendNum() | src/common/percent.c169-220 | Format percentage number |
ffTempsAppendNum() | src/common/temps.c6-65 | Format temperature with color |
ffOptionsParseDisplayJsonConfig() | src/options/display.c10-516 | Parse JSON display config |
ffOptionsParseDisplayCommandLine() | src/options/display.c528-847 | Parse CLI display options |
| Priority | Source | Parser |
|---|---|---|
| 1 (Highest) | Command-line arguments | ffOptionsParseDisplayCommandLine() |
| 2 | JSONC configuration files | ffOptionsParseDisplayJsonConfig() |
| 3 (Lowest) | Compiled defaults | ffOptionsInitDisplay() |
Sources: src/options/display.c src/fastfetch.c
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.