Building a Custom Theme for Apparix - Quick Guide

Hey everyone,

Figured I'd share what I've learned putting together a custom theme for Apparix since the docs are still catching up. Updated this post with everything that's been added recently.

Folder Structure

Your theme lives in content/themes/your-theme-name/ and here's the full structure:

my-theme/
├── theme.json              (required - theme manifest)
├── thumbnail.png           (optional - preview image)
├── screenshot.png          (optional - full screenshot)
├── layouts/
│   ├── main.php            (optional - layout override)
│   └── partials/
│       ├── header.php      (optional - partial override)
│       └── footer.php      (optional - partial override)
├── components/
│   └── product-card.php    (optional - component override)
├── assets/
│   ├── css/
│   │   └── theme.css       (your theme stylesheet)
│   ├── js/
│   │   └── theme.js        (optional scripts)
│   └── images/
│       ├── logo.svg
│       └── hero-bg.jpg
└── config/
    └── menus.json           (optional - menu config)

At minimum you need theme.json and optionally assets/css/theme.css for styling.

Important: No PHP files are allowed in theme packages. This is a security restriction enforced during upload. Layouts and components that need PHP overrides must be set up separately by the store admin.

theme.json

This is the heart of your theme. Here's a full example:

{
  "slug": "my-theme",
  "name": "My Theme",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A clean theme for Apparix",
  "logo": "/content/themes/my-theme/assets/images/logo.svg",
  "hero_image": "/content/themes/my-theme/assets/images/hero-bg.jpg",
  "colors": {
    "primary": "#3D1E0E",
    "secondary": "#E8736E",
    "accent": "#FFF5EB"
  },
  "fonts": {
    "heading": "Playfair Display",
    "body": "Inter"
  },
  "settings": {
    "navbar_bg_color": "#FFFFFF",
    "navbar_text_color": "#3D1E0E",
    "navbar_bg_image": "/content/themes/my-theme/assets/images/navbar-bg.jpg",
    "footer_bg_color": "#12121f",
    "footer_text_color": "#FFFFFF",
    "footer_bg_image": "/content/themes/my-theme/assets/images/footer-bg.jpg",
    "glow_color": "#E8736E",
    "hero_bg_start": "#E8736E",
    "hero_bg_end": "#D4564F",
    "layout_style": "full-width",
    "header_style": "standard",
    "category_layout": "grid",
    "product_grid_columns": 4,
    "logo_text_font": "Playfair Display",
    "logo_text_size": 28,
    "logo_text_weight": "700",
    "logo_text_stretch": "normal",
    "logo_text_spacing": "0.02em"
  },
  "effects": {
    "hover_animations": { "enabled": true, "speed": "normal" },
    "card_hover": { "enabled": true, "style": "lift" },
    "button_glow": { "enabled": true, "intensity": "subtle" },
    "background_animation": { "enabled": false, "style": "none" },
    "page_transitions": { "enabled": true, "style": "fade" },
    "shadow_style": "subtle",
    "border_radius": "slightly-rounded"
  }
}

The slug field must match your theme folder name. Required fields are slug and name — everything else is optional. The colors, fonts, settings, and effects sections map directly to what you see in the admin theme customizer.

Settings Explained

• navbar_bg_color / navbar_text_color - Navbar background and text colors
• navbar_bg_image - Background image for the navbar (optional)
• footer_bg_color / footer_text_color - Footer background and text colors
• footer_bg_image - Background image for the footer (optional)
• glow_color - Used for button glow effects and accent highlights
• hero_bg_start / hero_bg_end - Hero section gradient colors
• layout_style - Either sidebar or full-width
• header_style - standard, centered, or minimal
• category_layout - grid, list, or masonry
• product_grid_columns - Number of columns in the product grid (default 4)
• logo_text_font / logo_text_size / logo_text_weight / logo_text_stretch / logo_text_spacing - Fine-tune the logo text appearance using any Google Font

Theme Logo & Hero Image

You can bundle a logo and hero background image with your theme:

• "logo" - path to your theme logo (SVG, PNG, JPG, WebP). Replaces the store logo when your theme is active.
• "hero_image" - path to a hero background image for the homepage hero section.

Both are optional. If not set, the store falls back to its default logo and hero settings. Store owners can override these from the admin theme customizer after installing.

Layout, Partial & Component Overrides

Installed themes can override the platform's default templates:

• Layouts - Place files in layouts/ to override main.php, checkout.php, etc.
• Partials - Place files in layouts/partials/ to override header, footer, navbar, etc.
• Components - Place files in components/ to override product-card, category-card, etc.

The system checks for theme overrides first and falls back to the defaults if not found.

CSS Override Approach

Your assets/css/theme.css overrides the platform's default styles. The platform loads your theme CSS after main.css, so your rules take precedence. Use !important sparingly.

Key CSS variables the platform generates from your theme settings:

• --primary-pink, --secondary-pink, --light-pink - your theme colors
• --navbar-bg, --navbar-text - navbar colors
• --footer-bg, --footer-text - footer colors
• --hero-bg-start, --hero-bg-end - hero gradient
• --glow-color - glow/accent color
• --font-heading, --font-body - typography
• --product-grid-columns - grid layout
• --border-radius, --shadow, --transition - effect variables

You can also add a custom_css field in the admin customizer for quick CSS tweaks without editing theme files.

Hooks to Know About

• page_head - fires in the <head> tag, use it for injecting CSS or meta tags
• page_footer - fires before </body>, good for scripts
• navbar_menu_items - lets plugins add nav links

Call them with HookRegistry::doAction() or HookRegistry::applyFilters() in your layout.

Tips

• Keep the existing CSS class names if you want plugins to look right out of the box
• Static assets get served from /content/themes/your-theme-name/assets/
• Test with a few plugins active so you know nothing breaks
• Look at the default main.php layout as a reference, it's well structured
• Download the free Atelier theme from the marketplace to see a complete working example
• You can preview your theme without activating it using the admin preview mode
• Theme packages are uploaded as ZIP files through the admin panel

Honestly the hardest part is just getting the colors and effects dialed in. Once that clicks everything else falls into place. Happy to answer questions if anyone gets stuck.

---
Updated March 2026 with layout overrides, new settings fields, effects, and full theme.json reference.