Configuration

Default location: $XDG_CONFIG_HOME/hyprburst/config.toml, falling back to ~/.config/hyprburst/config.toml. No config file is required. A fully commented template ships as config.example.toml:

mkdir -p ~/.config/hyprburst
cp config.example.toml ~/.config/hyprburst/config.toml

`[window]`

Key	Type	Default	Notes
`window.app_id`	string	`"hyprburst"`	Wayland app-id. Legacy hyprlang rules must match it.
`window.placement`	string	`"centered"`	`"centered"` floating window, or `"fullscreen"` full-monitor overlay.
`window.width`	integer	`640`	Centered window width. Must be `>= 1`.
`window.height`	integer	`720`	Centered window height. Must be `>= 1`.
`window.transparent`	bool	`true`	Keep transparent for Hyprland blur. Set `false` for an opaque `colors.background`.
`window.opacity`	float	`0.85`	Compositor opacity on Lua Hyprland, and the opacity of the transparent background panel.

`[font]`

Key	Type	Default	Notes
`font.path`	string	unset	Explicit `.ttf`/`.otf` path. Wins over `$HYPRBURST_FONT`, `family` and fontconfig.
`font.family`	string	unset	fontconfig family used after `path` and `$HYPRBURST_FONT`. Ignored by `hyprburst tui`.
`font.size`	float	`20.0`	Logical font height in pixels. The cell size derives from the font’s metrics at this size.

`[layout]`

Key	Type	Default	Notes
`layout.mode`	string	`"list"`	`"list"` for one entry per row, `"grid"` for columns.
`layout.min_column_width`	integer	`20`	Grid mode only. Narrower cells collapse to fewer columns.
`layout.padding_horizontal`	integer	`4`	Columns of whitespace left and right. Capped at 32.
`layout.padding_vertical`	integer	`2`	Rows of whitespace above and below. Capped at 32.
`layout.center_banner`	bool	`false`	Horizontally center the banner.
`layout.separator`	bool	`false`	Draw a thin rule between banner/search and results.

`[ui]`

Key	Type	Default	Notes
`ui.show_banner`	bool	`false`	Draw the banner above the prompt.
`ui.banner`	string	built-in ASCII art	Banner content. Multi-line TOML string; empty hides it.
`ui.prompt`	string	`"> "`	Printed before the search cursor.
`ui.page_size`	integer	`10`	Entries per page (PageUp/PageDown step). Must be `>= 1`.
`ui.show_icons`	bool	`true`	Draw an icon before each app.
`ui.selected_marker`	string	`"> "`	Prefix drawn on the selected row.
`ui.cursor_char`	string	`"█"`	Single-character cursor glyph.
`ui.show_cursor`	bool	`true`	Draw the cursor glyph at all.

`[colors]`

Key	Default	Notes
`colors.banner`	`#c6a0f6`	ASCII banner color.
`colors.prompt`	`#8aadf4`	Prompt and cursor color.
`colors.selected`	`#f2d5ff`	Text of the highlighted entry.
`colors.selected_bg`	`#3a2e5a`	Highlight bar behind the selected row.
`colors.empty`	`#9a8cb5`	“No matches” message color.
`colors.background`	`#1a1b26`	GPU window background panel; TUI base background.
`colors.foreground`	`#c8cce0`	Base color for ordinary launcher text.

Each color accepts a 6-digit hex string like #ff79c6 or a named color: black, red, green, yellow, blue, magenta, cyan, white, gray/grey, darkgray/darkgrey, light-red, light-green, light-yellow, light-blue, light-magenta, light-cyan, or reset (terminal default).

Example: centered grid

[layout]
mode = "grid"
min_column_width = 28
padding_horizontal = 6
padding_vertical = 2
center_banner = true
separator = true

[ui]
prompt = "λ "
selected_marker = "▶ "
cursor_char = "▏"
show_icons = true

[colors]
banner   = "#ff79c6"
prompt   = "light-cyan"
selected = "#ffb86c"

Shared Swatches theme

[appearance] theme_file points at a Swatches v1 theme. Relative paths resolve against the config file’s directory; ~/ expands to $HOME. It is loaded once at launch, so reopen to apply edits.

Swatches role	hyprburst field
`background`	`colors.background`
`foreground`	`colors.foreground`
`accent`	`colors.prompt` and `colors.banner`
`muted`	`colors.empty`
`selection_background`	`colors.selected_bg`
`selection_foreground`	`colors.selected`
`font.family`	`font.family`

Explicit [colors] / [font] fields always win. A missing or invalid theme is a warning, not an error: the launcher still opens.

Environment variables

Variable	Purpose
`HYPRBURST_FONT`	Path to a `.ttf`/`.otf` cell font. Overrides `[font] family`; overridden by `[font] path`.
`HYPRBURST_DISPATCH`	`lua` or `legacy` to force the Hyprland dispatch form if auto-detection misfires.