UI Components
Audience: End users and non-technical stakeholders Last Updated: 2026-04-05 Version: 2.0.0
Overview
The UI Components system is the visual and interactive foundation of Llamafin. It provides a comprehensive suite of overlays (modals, alerts, toasts, popovers), player interfaces (full-screen player, visualizers, lyrics), interaction tools (selection, scroll optimisation, sleep timer), and device-aware features (haptics, keep-awake, theme adaptation).
The system is designed for performance, accessibility, and cross-platform consistency, automatically adapting to iOS, Android, Windows, macOS, and Linux environments.
Key Concepts
1. Overlay System
Llamafin uses several types of overlay components to communicate with users:
| Overlay Type | Purpose | Examples |
|---|---|---|
| Modals | Full-screen or partial-screen dialogues that capture focus | Full-screen player, download options, playlist creation, settings dialogues |
| Alerts | System-level notifications requiring user attention | Network connectivity loss, destructive action confirmations |
| Toasts | Brief, auto-dismissing messages | Success confirmations, error notifications, informational tips |
| Action Sheets | Bottom-sheet menus with contextual actions | Diagnostics export, text display lists |
| Popovers | Small anchored menus | Multi-select options, export choices, language picker |
2. Modal Stack System
Llamafin supports multiple simultaneous modals organised in a stack:
- Open a modal: It appears on top of the stack
- Close a modal: The topmost modal dismisses with a smooth animation
- Replace a modal: The topmost modal swaps to a new one without closing the stack
This enables complex workflows like opening download options from within the full-screen player without losing context.
3. Global Toast System
All notifications across the app flow through a unified toast system:
- Informational messages display for 5 seconds
- Error/failure messages stay on screen until you dismiss them
- Actionable toasts include a navigation arrow that takes you to the relevant page
- No stacking: Only one toast displays at a time to prevent screen clutter
4. Confirmation System
Destructive or significant actions require explicit confirmation:
- Delete server source
- Remove downloaded item
- Clear cache
- Delete playlist
- Trim history
- Quit application
Each confirmation dialogue is translated into your preferred language and can include input fields for custom values (e.g., custom cache size).
5. Player Views
The full-screen player offers 5 distinct view modes:
| View | Description |
|---|---|
| Cover | Standard album artwork display |
| Record | Vinyl record animation with spinning disc |
| Lyrics | Synchronised lyrics display |
| Visualiser | Real-time audio Visualisation (Butterchurn/MilkDrop compatible) |
| Turntable | Turntable animation view |
Your preferred view and visualizer are saved automatically and restored across sessions.
6. Visualizer System
Llamafin includes a Butterchurn audio visualizer (compatible with Winamp's MilkDrop):
- Real-time rendering synced to audio playback
- Multiple presets with smooth transitions (1.2-second crossfade)
- Quality settings adjustable based on device performance
- WebGL support detection for hardware-accelerated rendering
- Performance optimised: Runs outside the main UI thread to avoid frame drops
7. Theme System
Llamafin adapts to your visual preferences:
| Theme | Description |
|---|---|
| Light | Standard light theme |
| Dark | Dark background with light text |
| Black | Pure black background (AMOLED-friendly) |
| White | High-contrast white theme |
System Theme Tracking: When enabled, Llamafin automatically follows your device's light/dark mode setting and updates in real-time when the system preference changes.
8. Multi-Select & Selection System
Llamafin supports batch operations through multi-select mode:
- Per-context selection: Each list maintains its own independent selection state
- Toggle mode: Enter/exit multi-select without affecting other lists
- Visual feedback: Selected items are clearly highlighted
- Batch actions: Delete, download, add to playlist, and more on multiple items simultaneously
9. Virtual Scrolling
For large libraries (thousands of songs/albums), Llamafin uses virtual scrolling:
- Only visible items (plus a buffer) are rendered in the DOM
- Scroll position is tracked to determine which items to render
- Performance optimised: Prevents unnecessary re-renders with threshold-based updates
- Context-aware: Each list maintains independent scroll state
10. Sleep Timer
The sleep timer automatically pauses playback after a specified duration:
- Set a timer duration (e.g., 30 minutes, 1 hour)
- A countdown runs in the background
- When the timer expires, playback pauses and you receive a notification
- Cancel at any time from the player
11. Keep-Awake System
When watching the full-screen player or visualizer, Llamafin can prevent your device from sleeping:
- Automatically activates when full-screen player opens
- Deactivates when you close the player
- Respects your settings preference
- Uses native platform APIs (iOS/Android) for reliable behaviour
12. Haptic Feedback
On supported mobile devices, Llamafin provides haptic feedback for interactions:
- Selection start/changed/end: Subtle taps when interacting with lists
- Impact feedback: Customizable intensity for specific actions
- Toggle on/off: Controlled in Advanced Settings
- Automatic detection: Only available on devices with haptic hardware
13. Device-Aware UI
Llamafin adapts to your device characteristics:
| Adaptation | Description |
|---|---|
| Operating System | UI patterns adjust for iOS, Android, Windows, macOS, or Linux |
| Window Size | Responsive layout adapts to window dimensions (desktop) |
| Orientation | Detects portrait vs. landscape and adjusts layout |
| Custom Scrollbars | Platform-specific scrollbar styling where needed |
| Text Truncation | Adjustable text length limits based on screen size |
Shared Reusable Components
Llamafin includes a library of 50+ reusable UI components used throughout the application:
Audio Item Renderers
- Audio Item: Universal component for displaying songs, albums, artists in list, grid, or track modes. Handles download status, preview playback, multi-select, and background analysis indicators.
- Audio Item Image: Displays album/artist artwork with automatic fallback to generated placeholders.
- Mini Player: Persistent bottom player bar with playback controls, progress indicator, and tap-to-expand full-screen player.
Loading & Skeleton System
- Loading Shell: App initialisation screen with progress indicator, tips carousel, error recovery options, and force-offline mode button.
- Skeleton Loader: Placeholder animations while content loads.
- Llam Spinner: Advanced animated spinner with 30+ animation styles including ring, bars, pulse, wave, particles, DNA, plasma, equalizer, radar, vortex, kaleidoscope, constellation, vinyl, oscilloscope, and more. Supports audio-reactive mode and respects device "reduced motion" accessibility settings.
Layout Components
- Library Layout: Master layout supporting grid, list, and carousel display modes. Optimises visual effects (glass morphism, shadows) based on device hardware capabilities.
- Library FAB: Floating action button for quick access to common library actions.
- Page Header: Standardized page headers with consistent styling.
Marquee & Text Components
- Fast Marquee: Smooth scrolling text for long titles that overflow available space.
- Overflowing Text: Automatically switches between static text and marquee based on content length.
- Sliding Text: Animated text sliding animation for dynamic displays.
Progress Indicators
- Circle Progress: Circular progress indicator for downloads, caching, and other operations.
- Metric Charts: Chart.js-based charts for device metrics, history, and analytics.
Debug Overlays (Development/Advanced Users)
- Audio Debug: Audio engine status display
- FPS Counter: Real-time frame rate monitoring
- Performance Overlay: Performance metrics display
- Memory Overlay: Memory usage monitoring
Configuration
Appearance Settings
| Setting | Options | Description |
|---|---|---|
| Theme | Light, Dark, Black, White | Base application theme |
| Track System Theme | On, Off | Automatically follow device light/dark mode |
| Background Colours | Multiple presets | Player background colour palette |
| Font Family | System fonts, custom fonts | Typography for text elements |
| Visualizer Quality | Low, Medium, High, Ultra | Rendering quality for audio visualizers |
| Active Visualizer | 20+ presets | Choose your preferred visualizer preset |
| Player View | Cover, Record, Lyrics, Visualizer, Turntable | Default full-screen player view |
| Keep Screen On | On, Off | Prevent device sleep during playback |
Interaction Settings
| Setting | Options | Description |
|---|---|---|
| Haptics Enabled | On, Off | Enable haptic feedback on supported devices |
| Sleep Timer Duration | Custom duration | Default timer length |
Accessibility
| Setting | Description |
|---|---|
| Reduced Motion | Respects device setting to minimise animations |
| Custom Scrollbars | Platform-appropriate scrollbar styling |
| Text Truncation | Configurable text length limits |
How It Works
Modal Lifecycle
1. User taps button to open modal
↓
2. Modal is pushed onto the stack
↓
3. Modal renders via global registry (centralized host)
↓
4. CSS class applied for custom styling
↓
5. User interacts with modal content
↓
6. User dismisses modal (swipe, back button, or action)
↓
7. Animation plays (two-stage dismissal for smooth transitions)
↓
8. Modal removed from stack
↓
9. Return data captured for calling feature (if applicable)
Benefits:
- Consistent animation across all modals
- No visual glitches from premature removal
- Return data flows back to calling feature automatically
- Keep-awake automatically managed for full-screen player
Toast Notification Flow
1. Any feature performs action (download, delete, play, etc.)
↓
2. Feature dispatches action with message payload
↓
3. Unified toast listener intercepts the action
↓
4. Message text translated to user's language
↓
5. Toast displayed with appropriate styling (error=red, success=green, etc.)
↓
6. If actionable: navigation arrow button included
↓
7. Auto-dismisses after 5 seconds (errors stay until dismissed)
Benefits:
- No duplicate toast logic across features
- Consistent messaging behaviour
- Automatic i18n translation
- Actionable toasts reduce navigation friction
Virtual Scrolling Process
1. User scrolls through a long list
↓
2. Scroll position tracked (debounced to avoid excessive updates)
↓
3. Render window calculated: visible items + buffer (10 before, 40 after)
↓
4. Only items in render window are in the DOM
↓
5. Threshold check: only update if change exceeds half the buffer
↓
6. DOM updated with visible items
Benefits:
- Smooth scrolling even with 10,000+ items
- Minimal memory usage (only visible items rendered)
- No layout jank from excessive re-renders
Theme Application
1. User selects theme (or system theme changes)
↓
2. Theme action dispatched to store
↓
3. Effect applies theme via data-theme attribute on document body
↓
4. CSS custom properties update all component colours
↓
5. Preference saved to storage for next session
System Theme Tracking:
- Listens to
prefers-colour-schememedia query changes - Responds to both dark and light system preference changes
- Initial theme set based on system preference when tracking enabled
Visualizer Lifecycle
1. User switches to visualizer view
↓
2. Canvas element provided to visualizer system
↓
3. Butterchurn initialised with audio context and quality settings
↓
4. Active preset loaded with smooth transition
↓
5. When playback starts: AnalyserNode connected
↓
6. Rendering loop runs outside Angular zone (performance optimised)
↓
7. FPS throttled based on quality settings
↓
8. On quality change: clean destroy → reinit cycle
↓
9. On view change or component destroy: audio disconnected, resources freed
Benefits:
- No memory leaks from orphaned audio connections
- Smooth preset transitions (1.2-second crossfade)
- Performance adapts to device capabilities
- WebGL detected and used when available
Integration with Other Features
| Feature | Integration Point | Description |
|---|---|---|
| Network Status | Network Alert | Automatically shows alert when offline, hides when reconnected |
| Downloads | Download Options Modal | Chunked download progress, quality selection, smart download configuration |
| Player & Queue | Full-Screen Player | Player UI state drives view switching, visualizer, theme colours, fullscreen mode |
| Settings | Theme, Appearance, Interaction | Settings changes drive UI behaviour (theme, haptics, keep-awake, fonts) |
| Library | Multi-Select, Virtual Scroll | Selection and scroll systems enable batch operations and performant browsing |
| Connect P2P | Remote Control Modals | Cast menu, remote control control modals |
| DJ Mode | DJ Menu Modal | DJ configuration modal accessible from player |
| Sonic Analysis | Analysis Indicators | Background analysis shimmer on audio items |
| Device Metrics | Debug Overlays | Real-time FPS, memory, performance overlays |
Error Handling & Reliability
Modal Reliability
- Empty stack protection: Attempting to close a modal when none are open is safely ignored
- Two-stage dismissal: Animations complete before modal is removed from state, preventing visual glitches
- Auto-close on critical events: When all server sources are removed, source management and login modals close automatically
- Keep-awake synchronisation: Automatically activated/deactivated with full-screen player lifecycle
Toast Reliability
- No stacking: Only one toast displays at a time; new toasts dismiss the current one
- Error persistence: Failure toasts remain on screen until dismissed (no auto-dismiss) so you don't miss critical errors
- Navigation integration: Toasts with navigation URLs include an arrow button for quick context switching
- Translation safety: All toast text is translated; missing keys gracefully fall back to default language
Visualizer Reliability
- Clean lifecycle: Destroy → reinit cycle ensures no resource leaks on quality changes
- Audio connection management: AnalyserNode connected/disconnected based on playback status
- Error capture: initialisation failures captured with error messages displayed as toasts
- Graceful degradation: Falls back to non-WebGL rendering when hardware acceleration unavailable
Selection & Scroll Reliability
- Context cleanup: Each list must explicitly destroy its context when component is destroyed (prevents memory leaks)
- Threshold-based updates: Scroll render windows only update when change exceeds threshold (prevents excessive state updates)
- Map-based selection: O(1) lookups using
Mapdata structure for performance with large selections
Haptics Reliability
- Availability detection: Plugin availability checked at app initialisation
- Guard checks: Every haptic trigger verifies both availability and enabled state
- Settings synchronisation: Haptics enabled state stays in sync with advanced settings automatically
Technical Specifications
| Specification | Value | Description |
|---|---|---|
| Modal Types | 70+ | Unique modal types for different dialogues |
| ngFor-Managed Modals | 22 | Modals using two-stage dismissal animation |
| Shared Components | 50+ | Reusable UI components |
| Spinner Animation Types | 30+ | Different spinner Visualisation styles |
| Confirmation Action Types | 18 | Distinct destructive/significant actions requiring confirmation |
| Toast Message Types | 6 | Failure, Warning, Threat, Alert, Success, Information |
| Player Views | 5 | Cover, Record, Lyrics, Visualizer, Turntable |
| Theme Options | 4 | Light, Dark, Black, White |
| Virtual Scroll Buffer | 10 before, 40 after | Items rendered outside visible area |
| Scroll Update Threshold | 5 items | Half of RENDER_BUFFER_BEFORE |
| Toast Duration (Info) | 5 seconds | Auto-dismiss time for non-error toasts |
| Toast Duration (Error) | Indefinite | Stays until user dismisses |
| Long Press Duration | 300ms | Duration to trigger long press gesture |
| Long Press Cancel Distance | 15px | Max drag distance before cancelling |
| Visualizer Preset Transition | 1.2 seconds | Crossfade duration between presets |
| Haptic Styles | Variable | iOS/Android native haptic patterns |
| Supported Platforms | 7 | iOS, Android, Windows, macOS, Linux |
Related Documentation
- Architecture Overview -- Overall application architecture
- Audio Engine -- Audio system powering visualizers
- Player & Queue -- Full-screen player features
- Settings System -- Appearance and interaction settings
- Offline Support -- Network alert integration