# Handling Display Options in FastFetch: Architecture and Implementation
> Explore the architecture for handling display options in FastFetch. Learn how FFOptionsDisplay ensures consistent terminal formatting through defaults, command-line args, and JSON config.
- Repository: [fastfetch-cli/fastfetch](https://github.com/fastfetch-cli/fastfetch)
- Tags: architecture
- Published: 2026-03-30
---
**FastFetch centralizes all output customization in a global `FFOptionsDisplay` structure that is initialized with defaults, populated from command-line arguments or JSON configuration, and consumed as read-only state by every module to ensure consistent terminal formatting.**
FastFetch implements a centralized architecture for handling display options in fastfetch, storing all formatting preferences in a single configuration object that serves as the single source of truth for colors, separators, and numeric formatting. The design separates parsing logic from rendering logic, allowing modules to query display settings without duplicating validation code.
## Core Data Structure
The foundation of FastFetch's display handling is the `FFOptionsDisplay` struct defined in [`src/options/display.h`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/options/display.h). This structure aggregates every user-facing output customization into a single, flat configuration object.
```c
typedef struct FFOptionsDisplay {
/* colour handling */
FFstrbuf colorKeys; // “--color‑keys”
FFstrbuf colorTitle; // “--color‑title”
FFstrbuf colorOutput; // “--color‑output”
FFstrbuf colorSeparator; // “--color‑separator”
bool brightColor; // auto‑bright for dark terminals
/* key/value layout */
FFstrbuf keyValueSeparator; // “--separator”
FFModuleKeyType keyType; // “--key‑type”
uint16_t keyWidth; // “--key‑width”
uint16_t keyPaddingLeft; // “--key‑padding‑left”
/* numeric formatting */
int32_t stat; // “--stat”
bool pipe; // “--pipe”
bool hideCursor; // “--hide‑cursor”
bool disableLinewrap; // “--disable‑linewrap”
bool durationAbbreviation; // “--duration‑abbreviation”
FFSpaceBeforeUnitType durationSpaceBeforeUnit;
FFSizeBinaryPrefixType sizeBinaryPrefix;
uint8_t sizeNdigits;
uint8_t sizeMaxPrefix;
FFSpaceBeforeUnitType sizeSpaceBeforeUnit;
FFTemperatureUnit tempUnit;
uint8_t tempNdigits;
FFSpaceBeforeUnitType tempSpaceBeforeUnit;
uint8_t barWidth;
FFPercentageTypeFlags percentType;
uint8_t percentNdigits;
FFSpaceBeforeUnitType percentSpaceBeforeUnit;
uint8_t percentWidth;
int8_t freqNdigits;
FFSpaceBeforeUnitType freqSpaceBeforeUnit;
int8_t fractionNdigits;
FFFractionTrailingZerosType fractionTrailingZeros;
bool noBuffer;
FFlist constants; // user defined constants
} FFOptionsDisplay;
```
This struct lives inside the global configuration object `FFconfig` (declared in [`src/fastfetch.h`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/fastfetch.h)), ensuring all display parameters are accessible throughout the codebase.
## Global Instance Management
FastFetch uses a single global instance to host the display configuration. The `FFinstance` struct defined in [`src/fastfetch.h`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/fastfetch.h) contains both configuration and runtime state:
```c
typedef struct FFinstance {
FFconfig config;
FFstate state;
} FFinstance;
extern FFinstance instance; // defined in `src/common/init.c`
```
All modules read `instance.config.display` directly, which guarantees a single source of truth for output style. This global pattern eliminates the need to pass configuration pointers through every function call while maintaining thread-safe read-only access during execution.
## Configuration Initialization
During startup, FastFetch calls `ffOptionsInitDisplay(&instance.config.display)` to establish sane defaults. This function, implemented in [`src/options/display.c`](https://github.com/fastfetch-cli/fastfetch/blob/main/src/options/display.c), allocates internal buffers and sets default values such as `sizeBinaryPrefix = FF_SIZE_BINARY_PREFIX_TYPE_IEC`, `percentType = 9`, and default color strings.
The initialization sequence ensures that every field contains a valid value before any user input is processed, preventing undefined behavior when modules query display settings.
## Parsing User Input
FastFetch supports two input vectors for display options: command-line arguments and JSON configuration files. Both populate the same `FFOptionsDisplay` struct using dedicated parser functions.
### Command-Line Parsing
The `ffOptionsParseDisplayCommandLine` function receives each `--