# Theme Overview

## 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

{% hint style="info" %}
**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.
{% endhint %}

***

## Theme Contexts

**New in v0.6.3:** PteroCA supports multiple theme contexts, allowing you to use different themes for different parts of your panel.

### Available Contexts

PteroCA supports three distinct contexts:

| Context     | Description                 | Setting         | Use Case                                           |
| ----------- | --------------------------- | --------------- | -------------------------------------------------- |
| **panel**   | Admin panel and client area | `PANEL_THEME`   | Main panel interface, dashboard, server management |
| **landing** | Public landing page         | `LANDING_THEME` | Marketing site, homepage, public-facing pages      |
| **email**   | Email templates             | `EMAIL_THEME`   | Transactional emails, notifications                |

### How Context Works

Each theme declares which contexts it supports in its `template.json` file:

```json
{
  "template": {
    "name": "my-theme",
    "contexts": ["panel", "email"]
  }
}
```

This theme can be activated for panel and email contexts, but not for landing pages.

### Configuring Context-Specific Themes

You can set different themes for each context:

1. Navigate to **Settings → Theme**
2. Configure each context independently:
   * **Panel Theme** (`PANEL_THEME`) - Used for admin and client interfaces
   * **Landing Theme** (`LANDING_THEME`) - Used for public landing pages
   * **Email Theme** (`EMAIL_THEME`) - Used for email templates
3. Only themes supporting the specific context appear in each dropdown

**Example configuration:**

* Panel: "dark-professional" theme
* Landing: "marketing-bright" theme
* Email: "simple-email" theme

{% hint style="info" %}
**Single Theme for All Contexts**

If a theme supports all three contexts, you can use the same theme everywhere for consistent branding. Simply select it for all three settings.
{% endhint %}

***

## 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

### PteroCA Marketplace

{% hint style="success" %}
**PteroCA Marketplace** - Official Theme Repository

The [PteroCA Marketplace](https://marketplace.pteroca.com) is the primary source for verified, curated themes. Browse professional themes, read reviews, and download securely.

**Features:**

* ✅ Security-reviewed themes
* ✅ Community reviews and ratings
* ✅ Verified developers
* ✅ Version compatibility checking
* ✅ Official and community themes
* ✅ Free and premium themes

**Visit:** [marketplace.pteroca.com](https://marketplace.pteroca.com)
{% endhint %}

**Benefits of using the marketplace:**

* **Quality Assurance**: Themes are reviewed for quality and compatibility
* **Security**: Themes undergo security checks before listing
* **Support**: Direct contact with theme developers
* **Updates**: Easy access to theme updates and new versions
* **Reviews**: Read real user experiences before downloading

### Other Theme Sources

**Community Resources:**

* [PteroCA Discord Server](https://discord.com/invite/Gz5phhuZym) - Community theme sharing
* [GitHub](https://github.com/topics/pteroca-theme) - Open-source themes

**Third-Party Sources:**

* Developer portfolios and personal websites
* Custom theme commissions from developers

{% hint style="warning" %}
**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.

**Recommended:** Use the [PteroCA Marketplace](https://marketplace.pteroca.com) for verified, security-reviewed themes.
{% endhint %}

### Custom Themes

You can also commission custom themes from developers or create your own. See the [Creating Your Own Themes](#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

1. Download the theme from a trusted source
2. Extract the archive if it's in ZIP format
3. 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

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

**Example:**

```bash
# 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:

```bash
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:

1. Navigate to `/public/assets/theme/`
2. Create a folder matching your theme name (e.g., `my-theme`)
3. 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
```

{% hint style="info" %}
**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/`.
{% endhint %}

#### Step 5: Verify Installation

1. Log in to the Admin Panel
2. Navigate to **Settings → Theme**
3. Your theme should appear in the "Current theme" dropdown
4. If it doesn't appear, check the [Troubleshooting](#troubleshooting) section

***

## Activating Themes

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

### Activation Steps

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

**What happens when you activate a theme:**

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

{% hint style="success" %}
**Instant Theme Switching**

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

### Switching Back to Default

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

1. Go to **Settings → Theme**
2. Select **"default"** from the theme dropdown
3. Click Save

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

***

## Managing Themes

**New in v0.6.3:** PteroCA includes a comprehensive theme management interface for uploading, copying, exporting, and deleting themes.

### Accessing Theme Management

1. Log in to the **Admin Panel** with theme management permissions
2. Navigate to **Themes** in the left sidebar
3. View all installed themes with their details

### Theme List

The theme list displays:

* **Name**: Theme identifier and display name
* **Version**: Current theme version
* **Author**: Theme creator
* **Contexts**: Supported contexts (panel, landing, email)
* **Status**: Whether theme is currently active in any context
* **Actions**: Available operations (view, set default, copy, export, delete)

### Theme Operations

#### Viewing Theme Details

1. Click on a theme in the list
2. View comprehensive information:
   * Metadata (name, version, author, license)
   * Supported contexts
   * Compatibility (PteroCA version, PHP version)
   * Feature support (dark mode, custom colors)
   * Active status per context

#### Setting Default Theme

1. Click **Set Default** button next to a theme
2. Select the context (panel, landing, or email)
3. Confirm the change
4. Theme becomes active for that context immediately

**Requirements:**

* Theme must support the selected context
* User must have `set_default_theme` permission

#### Uploading Themes

Upload new themes as ZIP packages:

1. Click **Upload Theme** button
2. Select a theme ZIP file
3. System validates:
   * Valid `template.json` file
   * Correct directory structure
   * Unique theme name (no conflicts)
4. Theme is extracted and registered
5. Assets are published to public directory

**ZIP package structure:**

```
my-theme.zip
└── my-theme/
    ├── template.json
    ├── panel/
    ├── landing/
    ├── email/
    └── assets/
```

{% hint style="warning" %}
**Theme Name Conflicts**

If a theme with the same name already exists, upload will fail. Delete or rename the existing theme first, or use the Copy feature to create a variant.
{% endhint %}

#### Copying Themes

Create a copy of an existing theme:

1. Click **Copy** button next to a theme
2. Enter a new name for the copy
3. System creates duplicate with new name
4. Edit the copy without affecting the original

**Use cases:**

* Create theme variants (light/dark versions)
* Backup before making changes
* Build on existing themes

#### Exporting Themes

Export themes as ZIP packages:

1. Click **Export** button next to a theme
2. System packages theme files and assets
3. Download ZIP archive
4. Share with others or backup

**What's included:**

* All template files
* `template.json` metadata
* Assets (CSS, JS, images)
* Proper directory structure for re-upload

#### Deleting Themes

Remove themes from the system:

1. Click **Delete** button next to a theme
2. Confirm deletion
3. Theme files and database records are removed

**Restrictions:**

* Cannot delete the default theme
* Cannot delete currently active themes
* Must deactivate theme from all contexts first

{% hint style="danger" %}
**Deletion is Permanent**

Deleted themes cannot be recovered unless you have a backup. Consider exporting themes before deletion.
{% endhint %}

***

## 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:**

1. Click the color picker field
2. Choose a color or enter a hex code (e.g., `#FF5733`)
3. Preview updates in real-time
4. 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

{% hint style="info" %}
**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.
{% endhint %}

#### 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**

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

**Method 2: API**

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

**Response:**

```json
{
  "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:

```twig
<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_themes`     | View theme list          | Access the theme management interface  |
| `view_theme`        | View theme details       | See detailed theme information         |
| `set_default_theme` | Set default theme        | Activate themes for different contexts |
| `configure_theme`   | Configure theme settings | Adjust theme colors and options        |
| `upload_theme`      | Upload themes            | Install new theme packages             |
| `copy_theme`        | Copy themes              | Duplicate existing themes              |
| `export_theme`      | Export themes            | Download themes as ZIP packages        |
| `delete_theme`      | Delete themes            | Remove themes from system              |

### Default Permissions

* **Admin role**: Has all theme permissions by default
* **User role**: No theme permissions by default

For detailed information about the permission system, see [Access Control](https://docs.pteroca.com/access-and-permissions/access-control/roles-and-permissions).

***

## 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:**

1. **Verify template.json exists:**

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

2. **Validate JSON syntax:**

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

If jq reports an error, fix the JSON syntax.

3. **Check required fields:**

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

4. **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:**

1. **Check theme capabilities:**
   * Go to Settings → Theme
   * Click info icon next to theme name
   * Check "Allow configuring custom colors" option
2. **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)
3. **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:**

1. **Check theme capabilities:**
   * Verify theme has `"supportDarkMode": true` in template.json
2. **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:**

1. **Verify assets directory exists:**

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

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

```bash
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
```

4. **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:**

1. **Switch back to default theme via database:**

```bash
# Connect to database
mysql -u pteroca_user -p pteroca_db

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

2. **Clear cache:**

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

3. **Check logs:**

```bash
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:**

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

{% hint style="warning" %}
**Need More Help?**

If you're still experiencing issues:

* Check the [FAQ](https://docs.pteroca.com/help-and-maintenance/faq)
* Review [Troubleshooting Guide](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/help-and-maintenance/troubleshooting/README.md)
* Ask in the [Discord community](https://discord.com/invite/Gz5phhuZym)
* Contact your theme developer for support
  {% endhint %}

***

## Creating Your Own Themes

If you're a developer interested in creating custom themes for PteroCA, see the complete [**Theme Development Guide**](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/for-developers/themes/README.md) 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

***

## Related Documentation

### Configuration Guides

* [Theme Settings](https://docs.pteroca.com/customization-and-extensions/themes/theme-settings) - Detailed theme settings reference
* [General Settings](https://docs.pteroca.com/core-configuration/core-configuration/general-settings) - Site logo and branding
* [Access Control](https://docs.pteroca.com/access-and-permissions/access-control/roles-and-permissions) - Theme management permissions

### Customization

* [Overview](https://docs.pteroca.com/customization-and-extensions/customization) - General customization options
* [Plugins](https://docs.pteroca.com/customization-and-extensions/plugins/plugins) - Extend functionality with plugins

### Developer Resources

* [Theme Development](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/for-developers/themes/README.md) - Complete developer guide
* [Twig Documentation](https://twig.symfony.com/doc/3.x/) - Template engine reference

{% hint style="success" %}
**Need Help?**

If you have questions about themes or need assistance:

* Check the [FAQ](https://docs.pteroca.com/help-and-maintenance/faq)
* Review the [Theme Development Guide](https://github.com/PteroCA-Org/pteroca-homepage/blob/docs/for-developers/themes/README.md)
* Join our [Discord community](https://discord.com/invite/Gz5phhuZym)
* Report issues on [GitHub](https://github.com/PteroCA-Org/panel/issues)
  {% endhint %}