Frontend Components Architecture & Documentation
This document provides a technical overview of the React frontend architecture and components within Posterizarr's WebUI. The frontend is built using React (Vite) and styled with Tailwind CSS.
Architecture Overview
The frontend follows a component-based architecture located entirely within webui/frontend/src/. It is structured to handle configuration management, live monitoring, media galleries, and triggering backend jobs.
Directory Structure
components/: Reusable React components that make up the UI (pages, modals, forms, galleries).context/: React Context providers for global state management (Theme, Auth, Sidebar, Toast notifications).locales/: Internationalization (i18n) translation files.utils/: Helper functions for API fetching, date formatting, and logging.
Key Components (src/components/)
Layout & Navigation
- Responsive views: route layouts support narrow phones, tablets, and desktop screens. Action Center bulk/item controls wrap, Scheduler controls stack when needed, Logs filters stay stacked beside a tablet sidebar, and configuration token rows, setting keys, and library labels can shrink or wrap without hiding actions. Mobile form text uses a readable 16px size to avoid focus zoom in mobile browsers.
- Mobile navigation: the drawer has a viewport-bounded width, its own scroll region, background scroll locking, Escape dismissal, and automatic closing after navigation or switching to desktop width. Theme choices scroll on short screens. Notifications fit the phone width below the navigation bar.
- Dialog sizing: centered dialogs use
app-dialog-backdropon the fixed overlay andapp-dialog-panelon its panel. Shared phone rules bound panels to the dynamic viewport and safe-area insets, allow vertical scrolling, keep header/footer sections from shrinking, and size footer actions for touch. Preservemin-w-0on shrinking flex/grid children and use local horizontal scrolling for wide tables or code. The shared contract currently covers 54 panels; desktop dimensions remain component-owned. - Artwork and setup dialogs: image preview stacks artwork and details below desktop width; Action Center keeps compact, keyboard-accessible preview thumbnails visible on phones. Provider search wraps its title, filters, and search controls. Onboarding keeps the language selector separate from its mobile stepper and its footer outside the scrollable form.
-
Responsive verification: all 37 registered routes (including redirects) were audited at 320px, 768px, and 1440px; all nine configuration tabs were also checked with populated example settings and expanded groups. Interactive checks covered mobile navigation and representative add-library, YAML, variable-editor, sync, ratings-cache, image-preview fallback, and first-run dialogs, including 740x360 landscape. Tests used a local build with read-only API fixtures and blocked live writes. Conditional dialog content, real artwork delivery, device keyboards, and physical iOS/Android behavior still need release QA; shared bounds alone are not a claim that every possible dialog state was exercised.
-
App.jsx: The root component. Handles routing (React Router) and wraps the application in Context providers. - View loading: Dashboard and navigation stay eager. Other route views and onboarding use
React.lazywith aSuspenseloading state; routed content reusesErrorBoundaryfor recovery without removing navigation. Blueprints remains shared/eager because replacement-modal controls import it. Build chunks are split by actual route imports instead of manually grouping page modules with Dashboard. Sidebar.jsx: The main side navigation menu.TopNavbar.jsx: The top bar, housing breadcrumbs, user profile, and version badges. Main Posterizarr runs (including scheduled and recently-added triggers) and independent background jobs appear together, each with its own stop action where supported. Multiple jobs use compact, localized labels and icon stop buttons; the task strip scrolls horizontally when needed without covering the language, theme, or user controls. Ratings Refresh links directly to its live log. The existing top bar remains desktop/tablet-only.Dashboard.jsx: The primary landing page. Aggregates statistics, recent assets, and quick-action buttons.
Configuration & Settings
ConfigEditor.jsx: A dynamic form component for editing theconfig.json. It fetches tooltips from the backend and handles schema validation.OnboardingModal.jsx: The comprehensive first-run setup wizard that guides users through configuring media servers, artwork providers (with optional TVDb/Fanart credentials and live provider activation), schedules, libraries, and notifications.RunModes.jsx: Interface for selecting and triggering the various Posterizarr PowerShell modes (Normal, Backup, Sync, etc.).SchedulerSettings.jsx: UI for managing cron jobs and automated schedules, supporting standard PowerShell execution modes as well as lightweight Python-based Plex Sync jobs with granular library selection and asset type toggles (collections, posters, seasons, title cards, backgrounds).Blueprints.jsx: Interface for managing layout blueprints and recipes.LanguageOrderSelector.jsx&LanguageSwitcher.jsx: Components to handle UI language switching and the priority order of downloaded asset languages.ProviderOrderSelector.jsx: Drag-and-drop interface allowing users to configure the precise fallback order for metadata providers (TMDB, TVDB, Fanart, Plex).LibraryExclusionSelector.jsx: An inline and modal selector used during onboarding and configuration to include or exclude specific libraries from being processed.
Media & Assets Management
AssetsManager.jsx&AssetOverview.jsx: High-level views for managing generated posters, local assets, and storage usage.- Action Center paging:
AssetOverviewrequests/api/assets/overview/pagewith page size, tab, status, category, search, type, and library. Search is debounced; obsolete requests are aborted and ignored. Only visible rows are transferred during browsing, while counts and filter options describe the full result set. Filter controls remain mounted during refresh, selections retain their records across pages, and confirmed all-filtered bulk actions explicitly fetch all matching records before submitting changes. RecentAssets.jsx: Dashboard carousel displaying recently processed assets with direct integration intoAssetReplacerfor instant correction.GalleryHub.jsx,Gallery.jsx,SeasonGallery.jsx,TitleCardGallery.jsx,TestGallery.jsx: Interactive grids displaying generated artwork with lazy loading, filtering, pagination, and detailed inspection.BackgroundsGallery.jsx: Specialized gallery for viewing and selecting background source images.ManualAssets.jsx&FolderView.jsx: Tree and grid explorer for user-provided images under/manualassetsthat override automated scrapers.BackupAssets.jsx: Gallery view for inspecting and managing original images preserved under/assetsbackup.ImagePreviewModal.jsx: A modal component to view full-resolution posters, EXIF metadata, and provider links.AssetReplacer.jsx: Deep inspection and replacement modal for swapping out posters or logos on the fly.- Replacement metadata: when metadata is not supplied, export and image-choice requests include
rootfolderinstead of downloading complete libraries. Existing library and exact episode matching are preserved, and closing or switching the asset aborts obsolete metadata requests. AssetSearchModal.jsx: Provider search modal (TMDB, TVDB, Fanart) to find and apply replacement artwork or clearlogos by title or ID.LogoBrowser.jsx: Media server library browser for inspecting, filtering, and uploading missing ClearLogos directly to Plex, Jellyfin, or Emby.CollectionExplorer.jsx: Visual collection manager listing collections across connected media servers. Displays enriched collection metadata (item count and release year ranges, e.g.12 items • 1979 - 2024), Asset Details modal inspection (ImagePreviewModal.jsx), real-time diff status badges (In Sync,Update Ready,Missing on Plex,No Local Asset), quick diff view toggling (LOCALvsSERVER), 1-click single-poster push to Plex, batch out-of-sync push, and status filtering.CollectionLiveEditor.jsx: Real-time interactive collection poster designer featuring linear/radial gradients, top/bottom matte fades, vignettes, tiled grain, border radius, typography alignment/drop shadows, preset thumbnails, and direct media server uploads.
Monitoring & Status
DynamicOverlays.jsx: Sync & Maintenance has separate URL-addressable views for synchronization, media changes, asset title review, overlay cache, and ratings cache. Only the active view is rendered; shared settings, sync state, dialogs, and background jobs remain intact. Navigation supports keyboard arrows/Home/End, saved view selection, and legacytab=cachelinks.EpisodeTitleReview.jsx: Asset Title Review comparison across configured text-enabled episodes, seasons, movies, and shows with existing-artwork previews, eligibility reasons, media-type/status/reason/review-type filtering, bulk Hide selected, paged results, Fast Normal Run, and confirmed single/selected/all recreation through the existing asset queue rather than a separate renderer.LogViewer.jsx: A real-time terminal-like component that connects to the backend WebSocket to stream Posterizarr execution logs.QueueView.jsx: Displays backend task queue states (running, pending, completed, failed) with abort controls.RuntimeStats.jsx&RuntimeHistory.jsx: Charts and tables displaying historical execution metrics, date-range filtering (24H–ALL), aspect-aware asset thumbnails, Sample Telemetry Preview, and the embeddedOverlayDatabaseBrowser.jsxread-only multi-database inspector.SystemInfo.jsx: Displays host system resources (CPU, Memory, Alpine/Docker environment, versions).AssetsStats.jsx: Real-time counter widgets for library folders, poster counts, and total asset sizes.
Integrations & Export
PlexExport.jsx&JellyfinEmbyExport.jsx: Interfaces dedicated to managing metadata and artwork sync for specific media servers.AutoTriggers.jsx: UI to configure automated webhooks from Radarr, Sonarr, or Tautulli.PlexOAuthButton.jsx: Interactive OAuth component allowing users to log into Plex and automatically retrieve their server token.
Utility, Feedback & Modal Components
- Auto-Queue Changes: a standard checkbox appears directly below Add to Queue, only while queueing is on, in both Manual Mode and asset replacement dialogs. The shared preference persists as
auto_queue_changesin WebUI settings (defaultfalse). In Manual Mode, it keeps queueing selected after successful URL or upload submissions; the user still submits the completed form explicitly. In replacement dialogs, choosing provider artwork or selecting a ratio-validated upload submits it to the existing asset queue without a second replacement confirmation. The per-item queue switch stays on while this preference is active. Browsing, invalid uploads, and text-field edits alone do not submit anything. Existing parameter validation still applies, failed attempts remain available for manual retry, and duplicate in-flight replacement submissions are blocked. Queued success is reported as queued, not as an already completed replacement; parent completion callbacks are not invoked before processing, so Action Center entries are not removed just because work was queued. Logo selection retains its separate workflow. - Replacement while a run is active: while Posterizarr is running, asset replacement dialogs are not blocked. A chosen provider image or upload is queued and starts automatically when the current run finishes. If Add to Queue is switched on manually, the item waits for a manual queue start as before.
ConfirmDialog.jsx&ToastNotification.jsx: Reusable components for user feedback and destructive action confirmation.DangerZone.jsx: Renders emergency process and lock-reset controls, including a compact embedded mode insideDashboard.jsxshown only when an active script or.Runninglock file is detected.RestoreModeModal.jsx&ResetPostersModal.jsx: Targeted restore modal filtered by library, item title/folder, and asset type, alongside the library-selector modal for Reset Posters (filtered to supported movie and TV libraries).ValidateButton.jsx: Triggers backend configuration validation (CheckJson) with status feedback.About.jsx,VersionBadge.jsx,ReleasesSection.jsx,WhatsNewModal.jsx, &MarkdownRenderer.jsx: Redesigned About page (About.jsx) displaying live runtime environment details and sanitized one-click Copy System Info, inline expandable GitHub release changelogs (ReleasesSection.jsx+ XSS-safeMarkdownRenderer.jsxpowered bysrc/utils/markdownParser.js), visual version indicators (VersionBadge.jsx), and the one-time post-update "What's New" dialog (WhatsNewModal.jsx, integrated intoApp.jsx).ImageSizeSlider.jsx&CompactImageSizeSlider.jsx: UI controls for adjusting the size of items in gallery grids.ScrollToButtons.jsx: Floating helper to quickly navigate to the top or bottom of extensive media libraries.
Global State (src/context/)
AuthContext.jsx: Manages user authentication tokens, basic auth states, and session persistence.ThemeContext.jsx: Toggles between light, dark, and system color palettes using Tailwind CSS variables.ToastContext.jsx: Exposes a hook (useToast) to fire non-blocking notification alerts throughout the UI.SidebarContext.jsx: Manages responsive expansion/collapse states for the navigation sidebar.DashboardLoadingContext.jsx: Coordinates startup loading transitions, dashboard data prefetching, and splash screens.
Contribution Guidelines
When making a Pull Request to the React frontend:
- Styling: Always use Tailwind CSS utility classes. Avoid creating custom CSS in
index.cssunless absolutely necessary. - API Calls: Use the pre-configured wrappers in
src/utils/fetchInterceptor.jsfor API requests to ensure Auth headers and error handling are uniformly applied. - New Pages: If you create a new page component, be sure to add the route in
App.jsxand the navigation link inSidebar.jsx. - Localization: Do not hardcode user-facing strings. Use the
useTranslationhook and add keys to the JSON files insrc/locales/.