Configuration

histuid is configured via ~/.config/histui/histuid.toml.

Minimal Configuration

histuid works with no configuration file. All settings have sensible defaults.

Configuration File Location

~/.config/histui/histuid.toml

The configuration file is automatically loaded from this location if it exists.

Full Reference

log_level

Controls logging verbosity.

Value	Description
debug	Verbose debugging output
info	Normal operational messages (default)
warn	Warnings only
error	Errors only

log_level = "info"

Command-line override:

histuid --log-level debug

[display]

Controls notification popup position and behavior.

Key	Type	Default	Description
position	string	"top-right"	Popup position on screen
offset_x	int	10	Pixels from horizontal screen edge
offset_y	int	10	Pixels from vertical screen edge
max_visible	int	5	Maximum simultaneous popups (1-20)
monitor	int	0	Display monitor (0 = all, 1+ = specific monitor)
new_on_top	bool	false	New notifications appear at top of stack
image_data_preview_size	bytesize	"100 KiB"	Minimum size for showing image-data in body
layer	string	"top"	Wayland layer-shell layer

Valid Positions:

• top-right (default)
• top-left
• top-center
• bottom-right
• bottom-left
• bottom-center

note

Notification width and gap are controlled by the theme layout, not configuration. See Layout Reference for details.

Wayland Layer

The layer setting controls which Wayland layer-shell layer notifications appear on:

Value	Description
background	Bottom-most layer, below all windows
bottom	Above background but below normal windows
top	Above normal windows (default, correct for notifications)
overlay	Top-most layer, above everything including lock screens

[display]
layer = "top"  # Default - notifications appear above windows

# Use overlay to show notifications even on lock screen
layer = "overlay"

caution

Using overlay layer means notifications appear above lock screens. Only use this if you want notifications visible when the screen is locked.

Fullscreen Behavior

By default, Hyprland hides the TOP layer (alpha 0) when a fullscreen window is active. This affects all notification daemons on the TOP layer.

Current solutions:

1. Use the overlay layer - Notifications on the OVERLAY layer remain visible during fullscreen:

[display]
layer = "overlay"

caution

The OVERLAY layer appears above everything, including lock screens. Only use this if you want notifications visible when the screen is locked.

2. Accept fullscreen hiding - Keep layer = "top" (default) and notifications will be hidden during fullscreen, which some users prefer for immersive experiences.

Why layerrules don't help:

Hyprland's fullscreen fadeout directly sets layer alpha to 0 without checking layerrules. There is no alpha or nofullscreenfade layerrule - the no_anim rule only makes the hiding instant rather than preventing it.

Image Data Preview

The image_data_preview_size setting controls whether image-data from notifications is displayed in the popup body. Many messaging apps (Signal, Discord) send profile pictures via image-data which can clutter notifications.

Value	Meaning
"never" or "-1"	Never display image-data
"always" or "0"	Always display image-data
Size threshold (e.g., "100 KiB")	Only display if data size >= threshold

The default 100 KiB filters out profile pictures (typically 64-128px = ~64KB raw RGBA) while showing larger content like album art (300px+ = ~360KB+ raw).

tip

The image-path hint is always displayed since explicit file paths indicate intentional content images.

Byte Size Format:

Byte sizes can be specified as:

• "100" - 100 bytes
• "100 KB" or "100KB" - 100,000 bytes (SI, base 1000)
• "100 KiB" - 102,400 bytes (IEC, base 1024)
• "1 MB" - 1,000,000 bytes
• "1 MiB" - 1,048,576 bytes

See Icon Aliases for more details on how icons and images are handled.

[timeouts]

Controls how long notifications are displayed by urgency level.

Key	Type	Default	Description
low	duration	"0"	Timeout for low urgency (default: honor client)
normal	duration	"0"	Timeout for normal urgency (default: honor client)
critical	duration	"never"	Timeout for critical urgency
fallback	duration	"10s"	Fallback timeout when client says "server decides"

Timeout Values:

Value	Meaning
"0" or "0s"	Honor the client's requested timeout
"never" or "-1"	Notification never expires (must be dismissed)
Positive duration (e.g., "5s", "30s", "2m")	Override with this timeout

Duration Format:

Durations can be specified as:

• "5s" - 5 seconds
• "500ms" - 500 milliseconds
• "2m" - 2 minutes
• "1h30m" - 1 hour 30 minutes
• "5000" - 5000 milliseconds (integer)

Client Timeout Behavior:

When set to "0" (honor client), the daemon respects what the sending application requested:

• If the client requests -1 (server decides), the daemon uses the fallback timeout (default 10s, critical always uses 0/never)
• If the client requests 0 (never expire), the notification stays until dismissed
• If the client requests a positive value, that timeout is used

[history]

Controls notification history and retention.

Key	Type	Default	Description
max_notifications	int	500	Maximum notifications to keep (0 = unlimited)
store_images	bool	true	Store notification images for replay

Auto-Pruning Behavior:

The daemon automatically prunes old notifications to stay within limits:

• Buffer threshold: Pruning triggers when count exceeds max by 10% (e.g., at 550 for max 500)
• Debounce: At most one prune operation every 5 minutes
• Cascade cleanup: Images for pruned notifications are automatically deleted
• Startup prune: A prune runs on daemon startup to clean up any excess

This design prevents constant disk I/O while keeping history within reasonable bounds.

[behavior]

Controls daemon behavior.

Key	Type	Default	Description
stack_duplicates	bool	true	Combine identical notifications
show_count	bool	true	Show "(2)" for stacked duplicates
pause_on_hover	bool	true	Pause timeout when mouse hovers
history_length	int	100	Max notifications in session memory

[dnd]

Controls Do Not Disturb mode.

Key	Type	Default	Description
enabled	bool	false	Initial DnD state on daemon startup
suppress_critical	bool	false	Also suppress critical notifications in DnD mode

DnD Behavior:

• When DnD is enabled, notification popups and sounds are suppressed
• Notifications are still persisted to history for later review
• By default (suppress_critical = false), critical notifications bypass DnD and are still shown
• Set suppress_critical = true to also silence critical notifications when DnD is active
• Use histui dnd on/off/toggle to control DnD state

[mouse]

Controls mouse button actions on notification popups.

Key	Type	Default	Description
left	string	"dismiss"	Left-click action
middle	string	"do-action"	Middle-click action
right	string	"close-all"	Right-click action

Available Actions:

Action	Description
dismiss	Close this notification
do-action	Execute the "default" action if present (see below)
close-all	Close all visible notifications
context-menu	Show context menu (if supported)
none	Do nothing

Understanding Notification Actions

D-Bus notifications can include actions - interactive buttons or click behaviors. Actions are key/label pairs sent by the application:

• Key: An identifier sent back to the app when triggered (e.g., "reply", "default")
• Label: Human-readable text shown to the user (e.g., "Reply", "Open")

Special keys:

Key	Meaning
"default"	Action triggered by clicking the notification body (not a button)
Other keys	Displayed as action buttons in the notification

How do-action works:

When you configure a mouse button to do-action, clicking the notification:

1. Looks for an action with key "default"
2. If found, sends an ActionInvoked D-Bus signal back to the originating application
3. The application handles it (e.g., focusing its window, opening a conversation)

Common examples:

Application	Default Action	Effect
kitty/alacritty	Focus terminal window	["default", ""]
Discord	Open conversation	["default", ""]
Slack	Open thread	["default", "Open"]
Firefox	Focus tab	["default", ""]

Visual indicator:

Notifications with a "default" action display a subtle right-hand indicator (an inset shadow effect). This signals to users that the notification is "clickable." The indicator is styled via the .has-default-action CSS class.

See the CSS Reference for styling options.

Viewing actions in histui:

The histui TUI detail view shows all actions with their keys:

Extensions:
  Actions:
    default (no label) [click body to invoke]
    reply: Reply

[audio]

Controls notification sounds.

Key	Type	Default	Description
enabled	bool	true	Enable notification sounds
volume	int	80	Global volume (0-100)

Audio Behavior:

• Sounds are defined in theme manifests (see Theming)
• Only one sound plays at a time (newer sounds are skipped unless critical)
• Critical notifications can interrupt any playing sound
• Per-theme volumes are multiplied with the global volume

Supported Formats:

Format	Extension	Notes
WAV	.wav	PCM only (16-bit signed little-endian). IEEE Float format is not supported
Ogg Vorbis	.ogg	Fully supported
MP3	.mp3	Fully supported

Command-line Flags:

# Disable all sounds (overrides theme and config)
histuid --no-audio

# Override global volume (0.0 to 1.0)
histuid --volume 0.5

Example Configuration

# Logging: debug, info, warn, error
log_level = "info"

[display]
position = "top-right"
max_visible = 5
offset_x = 10
offset_y = 10
image_data_preview_size = "100 KiB"  # Filter small images like profile pics
layer = "top"                        # Wayland layer: background, bottom, top, overlay

[timeouts]
# Honor whatever the application requests (default for low/normal)
low = "0"
normal = "0"

# Critical notifications never expire (default)
critical = "never"

# Fallback timeout when client says "server decides" (-1)
fallback = "10s"

[behavior]
stack_duplicates = true
pause_on_hover = true

[dnd]
enabled = false           # Start with DnD off
suppress_critical = false # Critical notifications bypass DnD (default)

[mouse]
left = "dismiss"
middle = "do-action"
right = "close-all"

[audio]
enabled = true
volume = 80

[history]
max_notifications = 500   # 0 = unlimited
store_images = true       # Required for replay with images

Icon Aliases

Icon aliases are configured in a separate file for easy sharing:

~/.config/histui/icon-aliases.toml

This maps application names to standard icon names:

# ~/.config/histui/icon-aliases.toml

[aliases]
zapzap = "whatsapp"
telegram-desktop = "telegram"
firefox-esr = "firefox"
vesktop = "discord"
signal-desktop = "signal"

Built-in aliases are provided for common apps. User aliases take precedence. See Advanced Theming for more details.

See Also

• Theming - Customize appearance
• Monitor Mode - Run with dunst