Customization & Theming
Arcadia allows administrators to personalize the visual branding, landing pages, stylesheets, and assets of their instance.
Custom Landing Page
By default, visiting the root URL of an Arcadia instance displays the login view. If you wish to present a custom HTML landing page to unauthenticated visitors:
- In
config.yml, set:frontend: enable_custom_front_page: true - Place your custom HTML file at
public/home/index.html(inside the frontend directory or container). - When enabled, non-logged-in visitors landing on
/are served this page, while authenticated users are directed to the home page (HomeView.vue).
Unauthenticated Pages (Custom CSS & JS)
Pages accessible before signing in (/login, /register, /apply, /reset-password) cannot use the user-selectable CSS stylesheets configured in the database, because no user session exists.
To apply custom branding to these pages, create two optional, git-ignored files:
frontend/public/custom_unauth.css: Custom CSS rules loaded on unauthenticated pages.frontend/public/custom_unauth.js: Custom JavaScript executed on unauthenticated pages.
Note
Creating or editing these files requires updating the frontend (
docker compose up -d frontend --build)
Site Assets & Branding
You can replace the default placeholder graphics with your own site branding by replacing the following asset files:
| Asset | File Location | Purpose |
|---|---|---|
| Site Logo | frontend/src/assets/logo.svg | Main navbar logo (falls back to logo.example.svg if omitted) |
| Favicon | frontend/public/favicon.ico | Browser tab icon |
| Default Avatar | frontend/public/default_user_avatar.png | Fallback avatar for users who haven’t uploaded one |
Custom Icons (SVG Overrides)
Arcadia allows overriding any PrimeIcon across the frontend with a custom SVG file.
To replace an icon, place your .svg file into frontend/src/assets/custom-icons/ matching the PrimeIcon name without the pi- prefix:
- For example, to override the Bonus Points icon (
pi-wallet), save your SVG as:frontend/src/assets/custom-icons/wallet.svg - The build automatically generates CSS mask rules that replace the icon font glyph across the entire application with your SVG, seamlessly preserving theme colors (
currentColor), sizes, and hover effects.
Rebuilding
Custom icons and assets are inlined into the compiled frontend bundle. After adding or changing assets in frontend/src/assets/custom-icons/, rebuild the frontend. For example, with docker:
docker compose build frontend
docker compose up -d frontend
User Stylesheets (CSS Sheets)
Once users are logged in, Arcadia supports custom theme stylesheets. Users with the create_css_sheet and edit_css_sheet permissions can add and manage site-wide stylesheets through the Staff Dashboard:
- Each stylesheet is stored in the database (
css_sheetstable) with a unique name, CSS content, and an optional preview image. - Users can select their preferred active theme in their account settings.
- The instance’s default theme is defined in the site settings (
default_css_sheet_name, defaults toarcadia).