Themes

Complete guide to installing, managing, and customizing themes in PteroCA

Overview

Themes allow you to customize the visual appearance and user interface of your PteroCA panel. Introduced in v0.4, the theme system provides a flexible way to change colors, layouts, and the overall look of your installation without modifying core code.

What Themes Can Change

Themes control the appearance of:

Admin Panel Interface: Colors, layouts, and styling of the administrative interface
Client Area: Dashboard, server management, shop appearance
Authentication Pages: Login, registration, password reset pages
Email Templates: Branded email notifications
Error Pages: Custom 404, 500, and other error pages
Forms and Components: Input fields, buttons, and UI elements

Benefits of Using Themes

Consistent Branding: Match your panel to your company's visual identity
User Experience: Provide a unique and polished interface for your customers
Dark Mode Support: Many themes offer automatic light/dark mode switching
Easy Updates: Themes are isolated from core code, making PteroCA updates safer
No Code Required: Install and configure themes through the Admin Panel

Theme System Available in v0.4+

The theme system was introduced in PteroCA v0.4. If you're running an earlier version, please upgrade to access theme functionality.

Default Theme

PteroCA comes with a built-in default theme that provides a modern, professional interface.

Default Theme Features

Name: Default Theme
Version: 1.1.1
Author: PteroCA.com
License: MIT

Capabilities:

✅ Full dark mode support (automatic light/dark switching)
✅ Custom color configuration (primary colors for light and dark modes)
✅ Bootstrap 5 based design
✅ Responsive layout (mobile-friendly)
✅ EasyAdmin integration (admin panel interface)
✅ Custom error pages (404, 500)
✅ Email template styling

Default Colors:

Light mode primary: #4e73df (Blue)
Dark mode background: #2e59d9 (Darker Blue)

The default theme is always available as a fallback if another theme fails to load.

Finding Themes

Community Themes

While PteroCA is a newer platform, the community is growing. Here's where to look for themes:

Official Resources:

PteroCA Discord Server - Community theme sharing
GitHub - Open-source themes
PteroCA Forums (when available)

Third-Party Sources:

Developer portfolios and personal websites
Theme marketplaces (as ecosystem grows)
Custom theme commissions from developers

Download Themes from Trusted Sources

Only install themes from developers you trust. Themes have access to your panel's templates and can potentially include malicious code. Always review theme files before installation.

Custom Themes

You can also commission custom themes from developers or create your own. See the Creating Your Own Themes section for more information.

Installing Themes

Installing a theme involves placing the theme files in the correct directory and ensuring proper structure.

Prerequisites

Before installing a theme:

Access to your server's file system (SSH, SFTP, or file manager)
Theme files (usually provided as a ZIP archive or folder)
Write permissions on the /themes/ directory

Installation Steps

Step 1: Obtain Theme Files

Download the theme from a trusted source
Extract the archive if it's in ZIP format
Verify the theme folder contains a template.json file

Valid theme structure:

my-theme/
├── template.json          # Required: Theme metadata
├── base.html.twig        # Base template
├── assets/
│   ├── css/              # Stylesheets (optional)
│   ├── js/               # JavaScript (optional)
│   └── fonts/            # Custom fonts (optional)
├── panel/                # Admin panel templates (optional)
├── bundles/              # Bundle overrides (optional)
├── components/           # Reusable components (optional)
└── email/                # Email templates (optional)

Step 2: Upload Theme to Server

Connect to your server via SSH, SFTP, or file manager
Navigate to the PteroCA installation directory
Locate the /themes/ folder (e.g., /var/www/pteroca/themes/)
Upload/copy the theme folder into /themes/

Example:

# Via SSH
cd /var/www/pteroca/themes/
unzip my-theme.zip
# or
cp -r /path/to/my-theme ./

Result:

/var/www/pteroca/themes/
├── default/              # Default theme (always present)
│   └── template.json
└── my-theme/             # Your new theme
    └── template.json

Step 3: Set Permissions (if needed)

Ensure the web server can read the theme files:

chown -R www-data:www-data /var/www/pteroca/themes/my-theme
chmod -R 755 /var/www/pteroca/themes/my-theme

Replace www-data with your web server user if different (e.g., nginx, apache).

Step 4: Place Theme Assets (if applicable)

If the theme includes CSS, JavaScript, or image assets, place them in the public assets directory:

Navigate to /public/assets/theme/
Create a folder matching your theme name (e.g., my-theme)
Upload compiled assets (CSS, JS, images, fonts)

Example:

/public/assets/theme/
├── default/
│   ├── css/
│   ├── js/
│   └── fonts/
└── my-theme/
    ├── css/
    │   └── app.css       # Main stylesheet
    ├── js/
    │   └── custom.js     # Custom scripts
    └── img/
        └── logo.png      # Theme logo

Asset Directory Naming

The asset folder name must match your theme folder name. If your theme is /themes/my-theme/, assets must be in /public/assets/theme/my-theme/.

Step 5: Verify Installation

Log in to the Admin Panel
Navigate to Settings → Theme
Your theme should appear in the "Current theme" dropdown
If it doesn't appear, check the Troubleshooting section

Activating Themes

Once installed, you can activate a theme through the Admin Panel.

Activation Steps

Log in to the Admin Panel with an account that has theme management permissions
Navigate to Settings in the left sidebar
Click Theme in the settings menu
Locate the "Current theme of the panel" setting
Click Edit (pencil icon)
Select your desired theme from the dropdown list
(Optional) Click the ℹ️ icon next to a theme to view its information (version, author, features)
Click Save

What happens when you activate a theme:

✅ System validates the theme has a valid template.json
✅ Theme templates become active immediately (no restart needed)
✅ Theme assets are loaded on next page load
✅ Color and dark mode settings adjust based on theme capabilities
✅ Users see the new theme on their next page load

Instant Theme Switching

Theme changes take effect immediately. Simply refresh your browser to see the new theme in action.

Switching Back to Default

If you encounter issues with a custom theme, you can always switch back to the default theme:

Go to Settings → Theme
Select "default" from the theme dropdown
Click Save

The system automatically falls back to the default theme if an active theme is invalid or missing.

Theme Configuration

Many themes support customization options, allowing you to adjust colors and appearance without modifying theme files.

Available Configuration Options

The configuration options available depend on your active theme's capabilities:

1. Current Theme

Setting: Current theme of the panel

Description: Select which theme is active for your panel.

Available for: All installations

How to use:

Select from dropdown of installed themes
Click the info icon to see theme details
Save to apply immediately

2. Custom Colors (if supported)

Settings:

Default color for light mode - Primary UI color in light mode
Default background color for dark mode - Background color in dark mode

Description: Customize the color scheme of your theme without editing CSS files.

Available for: Themes with supportCustomColors: true in template.json

How to use:

Click the color picker field
Choose a color or enter a hex code (e.g., #FF5733)
Preview updates in real-time
Click Save to apply globally

What these colors affect:

Light mode color: Buttons, links, active menu items, highlights
Dark mode color: Sidebar background, content area background, dark mode UI elements

Theme Must Support Custom Colors

If you don't see color configuration options, your active theme doesn't support custom colors. Switch to a different theme or contact the theme developer.

3. Dark Mode Settings (if supported)

Setting: Disable dark mode

Description: Completely disable dark mode for all users.

Available for: Themes with supportDarkMode: true in template.json

Options:

Unchecked (default): Users can toggle between light and dark modes
Checked: Dark mode is disabled; users only see light mode

Use cases:

Your branding requires light mode only
Dark mode conflicts with custom styling
Simplify user interface options

Setting: Default theme mode

Description: Set the default color scheme for users who haven't chosen a preference.

Available for: Themes with dark mode support and dark mode not disabled

Options:

Light: Always use light mode by default
Dark: Always use dark mode by default
Auto: Follow user's system preference (operating system dark mode setting)

Note: Users can still override this preference in their account settings unless dark mode is completely disabled.

Configuration Best Practices

Choose colors carefully:

Test colors in both light and dark modes
Ensure sufficient contrast for readability
Consider color blindness accessibility
Preview on different devices and screen sizes

Dark mode considerations:

If your brand has strict color requirements, consider disabling dark mode
Auto mode provides the best user experience for most users
Test custom colors in both modes before finalizing

Theme Features and Capabilities

Themes can declare which features they support in their template.json file.

Feature Flags

Themes use feature flags to indicate capabilities:

Feature

Description

Impact on Admin Settings

supportDarkMode

Theme supports light and dark color schemes

Shows dark mode configuration options

supportCustomColors

Allows admin to configure custom colors

Shows color picker fields in settings

How to Check Theme Features

Method 1: Admin Panel

Go to Settings → Theme
Click the ℹ️ icon next to a theme name
View "Options" section showing supported features

Method 2: API

curl -X GET https://your-panel.com/panel/api/template/theme-name \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Response:

{
  "Template name": "my-theme",
  "Version": "1.0.0",
  "Options": {
    "Support dark mode": true,
    "Allow configuring custom colors": true
  }
}

What Happens When Features Are Disabled

If supportDarkMode: false:

Dark mode settings hidden in Admin Panel
Users cannot toggle dark mode
Theme always displays in light mode

If supportCustomColors: false:

Color picker fields hidden in Admin Panel
Theme uses its built-in color scheme
Custom colors cannot be applied

Theme Assets and Resources

Themes use assets like CSS, JavaScript, images, and fonts to create their visual appearance.

Asset Structure

Theme source files: /themes/{theme-name}/assets/

May contain source files (SCSS, uncompiled JS)
Not directly served to browsers

Public compiled assets: /public/assets/theme/{theme-name}/

Compiled and optimized files
Served directly to users' browsers
Accessible via web URLs

Asset Types

CSS Stylesheets:

Main styles: app.css
Page-specific: panel.css, errors.css
Loaded automatically by theme

JavaScript:

Custom interactive features
Libraries (Chart.js, etc.)
Loaded in theme templates

Images:

Logos, icons, backgrounds
Referenced in templates or CSS

Fonts:

Custom typography
Web fonts (WOFF2, TTF)

How Assets Are Loaded

Themes reference assets using the template_asset() Twig function:

<link rel="stylesheet" href="{{ template_asset('css/app.css') }}">
<script src="{{ template_asset('js/custom.js') }}"></script>

Generated URL:

https://your-panel.com/assets/theme/my-theme/css/app.css
https://your-panel.com/assets/theme/my-theme/js/custom.js

Asset Best Practices

For theme installation:

Always place assets in /public/assets/theme/{theme-name}/
Match folder name exactly to theme name
Ensure proper file permissions (readable by web server)

For troubleshooting:

Check browser console for 404 errors on assets
Verify asset files exist in public directory
Check web server has read access to asset files

Permissions

To manage themes, users need specific permissions:

Permission

Action

Description

access_settings_theme

View theme settings

Read-only access to theme configuration

edit_settings_theme

Modify theme settings

Change active theme and configure colors

Default Permissions

Admin role: Has both permissions by default
User role: No theme permissions by default

Assigning Permissions

To give users theme management access:

Navigate to Admin Panel → Roles
Create or edit a role
Enable theme permissions under "Settings - Theme" section
Assign the role to users

For detailed information about the permission system, see Access Control.

Troubleshooting

Common issues and solutions when working with themes.

Theme Not Appearing in Selection

Symptoms: Installed theme doesn't show up in the theme dropdown.

Possible causes:

Missing template.json file
Invalid JSON syntax in template.json
Incorrect folder structure
Missing required fields in template.json

Solutions:

Verify template.json exists:

ls /var/www/pteroca/themes/my-theme/template.json

Validate JSON syntax:

cat /var/www/pteroca/themes/my-theme/template.json | jq .

If jq reports an error, fix the JSON syntax.

Check required fields:

{
  "template": {
    "name": "my-theme",
    "version": "1.0.0",
    "pterocaVersion": "0.6",
    "phpVersion": ">=8.2"
  }
}

Verify folder name matches template name: Folder: /themes/my-theme/ JSON: "name": "my-theme" (must be identical)

Custom Colors Not Applying

Symptoms: Color picker settings don't change the panel appearance.

Cause: Theme doesn't support custom colors.

Solutions:

Check theme capabilities:
- Go to Settings → Theme
- Click info icon next to theme name
- Check "Allow configuring custom colors" option
If feature is missing:
- Switch to a theme with custom color support
- Contact theme developer to request feature
- Use the default theme (supports custom colors)
Clear browser cache:
- Press Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)
- Clear cached images and files
- Refresh page

Dark Mode Settings Not Visible

Symptoms: Can't find dark mode configuration options.

Cause: Theme doesn't support dark mode.

Solutions:

Check theme capabilities:
- Verify theme has "supportDarkMode": true in template.json
Switch themes:
- Choose a theme with dark mode support
- Default theme supports dark mode

Theme Assets Not Loading (404 Errors)

Symptoms: Broken styling, missing images, browser console shows 404 errors.

Causes:

Assets not uploaded to /public/assets/theme/{theme-name}/
Incorrect folder name (doesn't match theme name)
File permissions issue

Solutions:

Verify assets directory exists:

ls /var/www/pteroca/public/assets/theme/my-theme/

Check folder name matches:
- Theme folder: /themes/my-theme/
- Asset folder: /public/assets/theme/my-theme/
- Names must match exactly
Set correct permissions:

chown -R www-data:www-data /var/www/pteroca/public/assets/theme/my-theme
chmod -R 755 /var/www/pteroca/public/assets/theme/my-theme

Check asset paths in templates:
- Ensure theme uses template_asset() function
- Verify file paths are correct

Theme Causes Errors or Blank Pages

Symptoms: Panel shows errors or blank pages after activating theme.

Immediate fix:

Switch back to default theme via database:

# Connect to database
mysql -u pteroca_user -p pteroca_db

# Update theme setting
UPDATE setting SET value = 'default' WHERE name = 'current_theme';
exit;

Clear cache:

cd /var/www/pteroca
php bin/console cache:clear

Check logs:

tail -f var/log/prod.log

Root cause solutions:

Contact theme developer with error logs
Ensure theme is compatible with your PteroCA version
Verify all theme files are uploaded correctly
Check PHP error logs for template syntax errors

Theme Appears Outdated or Incompatible

Symptoms: Warning message about theme compatibility.

Cause: Theme's pterocaVersion requirement is older than your PteroCA installation.

Solutions:

Check theme version:
- Look for theme updates from developer
- Verify theme supports your PteroCA version
Update theme:
- Download latest version
- Replace theme files (backup old version first)
- Test in a staging environment if possible
Use default theme:
- Always up-to-date with PteroCA releases
- Switch back until theme is updated

Need More Help?

If you're still experiencing issues:

Check the FAQ
Review Troubleshooting Guide
Ask in the Discord community
Contact your theme developer for support

Creating Your Own Themes

If you're a developer interested in creating custom themes for PteroCA, see the complete Theme Development Guide in the "For Developers" section.

The developer guide includes:

Theme structure and file organization
Template.json schema and validation
Twig templating and template hierarchy
CSS styling and color customization
JavaScript integration
Asset management and compilation
Testing and debugging themes
Best practices for theme development

Configuration Guides

Theme Settings - Detailed theme settings reference
General Settings - Site logo and branding
Access Control - Theme management permissions

Customization

Overview - General customization options
Plugins - Extend functionality with plugins

Developer Resources

Theme Development - Complete developer guide
Twig Documentation - Template engine reference

Need Help?

If you have questions about themes or need assistance:

Check the FAQ
Review the Theme Development Guide
Join our Discord community
Report issues on GitHub

PreviousPlugins NextPterodactyl Integration

Last updated 1 day ago

Overview

What Themes Can Change

Benefits of Using Themes

Default Theme

Default Theme Features

Finding Themes

Community Themes

Custom Themes

Installing Themes

Prerequisites

Installation Steps

Step 1: Obtain Theme Files

Step 2: Upload Theme to Server

Step 3: Set Permissions (if needed)

Step 4: Place Theme Assets (if applicable)

Step 5: Verify Installation

Activating Themes

Activation Steps

Switching Back to Default

Theme Configuration

Available Configuration Options

1. Current Theme

2. Custom Colors (if supported)

3. Dark Mode Settings (if supported)

Configuration Best Practices

Theme Features and Capabilities

Feature Flags

How to Check Theme Features

What Happens When Features Are Disabled

Theme Assets and Resources

Asset Structure

Asset Types

How Assets Are Loaded

Asset Best Practices

Permissions

Default Permissions

Assigning Permissions

Troubleshooting

Theme Not Appearing in Selection

Custom Colors Not Applying

Dark Mode Settings Not Visible

Theme Assets Not Loading (404 Errors)

Theme Causes Errors or Blank Pages

Theme Appears Outdated or Incompatible

Creating Your Own Themes

Related Documentation

Configuration Guides

Customization

Developer Resources