Configuration

xtop persists its configuration automatically on quit. The file is config.json in the platform config directory, next to the themes/ and layouts/ folders:

~/.config/xtop/config.json                (Linux)
~/Library/Application Support/xtop/       (macOS)
%APPDATA%\xtop\                           (Windows)

On Linux you can override the base directory with $XDG_CONFIG_HOME.

Keys

Key	Type	Default	Description
`theme`	string	`"x"`	Currently selected color theme name (one of the 12 shipped or a user theme).
`layout_mode`	string	`"Dashboard"`	Built-in layout mode. One of `Dashboard`, `Vertical`, `Horizontal`, `CpuFocus`, `MemoryFocus`, `NetworkFocus`, `ProcessFocus`. Ignored while `layout_name` names a valid custom layout.
`layout_name`	string	`""`	Name of the active layout when it is a custom (non-built-in) layout. When non-empty and found, it takes precedence over `layout_mode`.
`update_interval_ms`	integer	`1000`	Sampling interval in milliseconds. Clamped to 100–3,600,000 on load.
`history_points`	integer	`100`	Data points retained for the historical charts.
`alerts`	object	see below	Alert thresholds; see Alert Thresholds.
`keybindings`	object	see below	Key bindings per action; see Keybindings.
`style`	object	see below	Widget glyph style (chart charset, borders, packs); see Style.
`effect`	string (optional)	absent	Frame effect applied to every rendered frame: `"fade"` activates the built-in fade-in (only in builds compiled with the `effects` feature). Any other value disables effects.

Example

{
  "theme": "miami",
  "layout_mode": "Dashboard",
  "layout_name": "",
  "update_interval_ms": 1000,
  "history_points": 100,
  "alerts": {
    "cpu_high": 90.0,
    "mem_high": 90.0,
    "disk_high": 90.0
  },
  "keybindings": {
    "quit": ["q"],
    "help": ["?"],
    "next_theme": ["t"],
    "prev_theme": ["T"],
    "next_layout": ["l"],
    "toggle_fullscreen": ["f"],
    "cycle_fullscreen": ["F"],
    "search": ["/"],
    "command_palette": ["ctrl+p", "ctrl+P"],
    "cancel": ["escape"],
    "kill_process": ["k"],
    "process_up": ["up"],
    "process_down": ["down"],
    "cycle_sort": ["s"]
  },
  "style": {
    "charset": "braille",
    "borders": "native",
    "pack": null,
    "widgets": {}
  }
}

Unknown keys and missing optional keys are ignored; a file that cannot be parsed falls back to the defaults above.

Alert Thresholds

When a metric exceeds its configured threshold, the corresponding widget changes color to red and displays a warning indicator in its title.

Key	Description	Default
`cpu_high`	CPU usage percentage that triggers a warning	90.0
`mem_high`	Memory usage percentage that triggers a warning	90.0
`disk_high`	Disk usage percentage that triggers a warning	90.0

Keybindings

Every action accepts a list of key strings; the first matching key wins. Keys are written as: single characters ("q", "/", "?"), shifted characters ("T", "F"), modified keys ("ctrl+p", "alt+x") and named keys ("escape", "enter", "backspace", "tab", "up", "down", "left", "right", "delete", "home", "end", "pageup", "pagedown").

Key (action)	Default binding	Action
`quit`	`["q"]`	Save config and quit
`help`	`["?"]`	Toggle the help overlay
`next_theme`	`["t"]`	Next theme
`prev_theme`	`["T"]`	Previous theme
`next_layout`	`["l"]`	Next layout
`toggle_fullscreen`	`["f"]`	Toggle full-screen view
`cycle_fullscreen`	`["F"]`	Cycle the full-screen widget
`search`	`["/"]`	Start process search
`command_palette`	`["ctrl+p", "ctrl+P"]`	Open the command palette (ctrl+p also works as a hardcoded fallback)
`cancel`	`["escape"]`	Cancel search / close overlays
`kill_process`	`["k"]`	Kill the selected process (same-user safety check)
`process_up`	`["up"]`	Move the process selection up
`process_down`	`["down"]`	Move the process selection down
`cycle_sort`	`["s"]`	Cycle the process sort column (CPU% → Memory → PID → Name)

Style

The style object controls widget glyphs. Values are the ecosystem-wide enums from xtop-widget-api:

charset: braille (default), dot, block, half_block, bar — chart markers used by history charts.
borders: native (default, classic single-line frame), rounded, double, plain, ascii (plain/ascii draw a pure ASCII +-| frame).
pack: widget pack used for every widget without a per-widget override ("default" or "blocks" when compiled with the widget-blocks feature).
widgets: map of widget-name overrides, each accepting charset, borders and pack.

See customization.md for an example and the full per-widget semantics.

Custom Themes and Layouts

For custom themes and layouts, see the customization guide.

Back to README

FilesExpand file tree

configuration.md

Latest commit

History