Configuration Overview¶
hyprlax supports two configuration formats:
- TOML (recommended) - Modern, feature-rich configuration
- Legacy (.conf) - Simple text-based format
Configuration Methods¶
1. Command Line¶
Quick configuration without files:
hyprlax --shift 200 --duration 1.5 --fps 60 image.jpg
2. TOML Configuration (Recommended)¶
Advanced features with structured configuration:
hyprlax --config ~/.config/hyprlax/hyprlax.toml
See TOML Reference for complete documentation.
3. Legacy Configuration¶
Simple text-based format:
hyprlax --config ~/.config/hyprlax/parallax.conf
See Legacy Format for syntax.
Quick Comparison¶
| Feature | Command Line | Legacy Config | TOML Config |
|---|---|---|---|
| Basic settings | ✅ | ✅ | ✅ |
| Multi-layer | ✅ (--layer) | ✅ | ✅ |
| Per-layer controls | Limited | Limited | ✅ Full |
| Cursor parallax | ✅ | ❌ | ✅ Full |
| Content fitting | ❌ | ❌ | ✅ |
| Advanced easing | ✅ (global) | ❌ | ✅ |
| Parallax modes | ✅ | ❌ | ✅ |
Configuration Priority¶
Settings are applied in this order (later overrides earlier): 1. Built-in defaults 2. Configuration file (TOML) 3. Environment variables 4. Command-line arguments 5. Runtime IPC commands
File Locations¶
hyprlax searches for configs in:
1. Path specified with --config
2. $XDG_CONFIG_HOME/hyprlax/ (usually ~/.config/hyprlax/)
3. Current directory
Migrating to TOML¶
Moving from legacy format? See Migration Guide.
Examples¶
Ready-to-use configurations are available under examples:
- Basic parallax
- Cursor tracking
- Multi-layer depth
Getting Started¶
- New users: Start with TOML Reference
- Legacy users: See Migration Guide
- Quick setup: Copy an example and customize
Validation¶
Test your configuration:
hyprlax --config your-config.toml --debug
This will report any configuration errors before starting.