← Back to DevBytes
Developer Tutorial July 10, 2026 16 min read

Helix Themes and Customization: Complete Guide

Understanding the Helix Framework

Helix is a powerful, modern template framework originally built for Joomla that has evolved into a comprehensive design system. It provides developers with a robust foundation for creating highly customizable, responsive themes without the repetitive boilerplate code typically associated with CMS template development. At its core, Helix offers a drag-and-drop layout builder, advanced typography controls, mega menu support, and an integrated customization panel that exposes hundreds of design variables through a unified interface.

The framework ships in two primary flavors: Helix Ultimate, the current flagship version built on Bootstrap 4 and modern JavaScript practices, and Helix 3, the legacy version still in wide use across thousands of production sites. Both versions share a common philosophy — separate configuration from presentation, keep markup semantic, and empower both developers and end-users to shape the visual experience without touching core files.

Why Helix Customization Matters

🚀 Deploy your AI agent in 10 minutes

Managed Hermes hosting. Zero DevOps. 100M tokens/mo included.

Try it free →

Customizing a Helix theme goes far beyond changing a few colors in a CSS file. The framework's architecture allows you to control layout dimensions, typography scales, spacing ratios, breakpoint behavior, and component-level styling from a centralized admin panel. This matters because it dramatically reduces the development cycle for client projects — you can prototype a fully branded site in hours rather than days. More importantly, Helix preserves customization through updates. When the framework core receives security patches or feature enhancements, your customizations remain intact because they live in override files and configuration data, not in modified core templates.

For agencies and freelancers, this means you can build a library of reusable theme presets, export them as JSON configuration files, and deploy them across multiple installations with a single import. The time savings compound with every project, and the consistency ensures that branding guidelines are enforced at the framework level rather than through ad-hoc CSS patches.

Setting Up Your Development Environment

Before diving into customization, you need a proper local development setup. The recommended approach uses a LAMP or LEMP stack with Node.js for compiling assets. Here is the complete setup sequence:

# 1. Create project directory
mkdir helix-project && cd helix-project

# 2. Download Helix Ultimate framework
git clone https://github.com/JoomShaper/helix-ultimate.git

# 3. Install Node dependencies for asset compilation
cd helix-ultimate
npm install

# 4. Install Gulp globally for build tasks
npm install -g gulp-cli

# 5. Run the default build task
gulp

# 6. Watch for changes during development
gulp watch

Once the build process completes, you will find the compiled template package ready for installation inside the dist/ directory. The gulp watch command monitors your source SCSS and JavaScript files, automatically recompiling on save — this is essential for an efficient customization workflow.

Theme File Structure Deep Dive

Understanding the directory layout is critical for effective customization. Here is the canonical structure of a Helix Ultimate template:

templates/
└── shaper_helixultimate/
    ├── assets/
    │   ├── css/            # Compiled stylesheets
    │   ├── js/             # Compiled JavaScript
    │   ├── images/         # Template images and icons
    │   └── scss/           # Source SCSS files (customization target)
    │       ├── components/
    │       ├── layouts/
    │       ├── sections/
    │       └── themes/
    ├── features/           # Feature-specific overrides
    ├── helix/              # Framework core (never modify directly)
    ├── layouts/            # Layout XML definitions
    ├── overrides/          # Joomla view overrides
    ├── templateOptions.php # Admin panel configuration
    └── templateDetails.xml # Template manifest

The golden rule of Helix customization: never modify files inside the helix/ directory. These core files are overwritten during framework updates. Instead, all customizations should go into assets/scss/, overrides/, or the admin panel configuration. This separation ensures your work survives version upgrades intact.

Customization Through the Admin Panel

Global Color Scheme Configuration

The Helix admin panel exposes a complete color system. Rather than hard-coding hex values in CSS, you define your palette through the interface, and the framework generates all necessary styles dynamically. The color system includes:

These variables map directly to SCSS variables in the source files. When you save changes in the admin panel, Helix writes the values to a configuration object stored in the database and injects them as CSS custom properties on page load. You can override any of these at the component level using the page-specific settings tab.

Typography System Configuration

Helix's typography system gives you granular control over every text element. The framework uses a modular scale approach where you define a base font size and a scaling ratio, and all heading levels, blockquotes, and special text elements are calculated automatically. In the admin panel, you can set:

# Typography configuration example (stored as JSON)
{
  "body_font_family": "Inter",
  "body_font_size": "16px",
  "body_font_weight": "400",
  "body_line_height": "1.6",
  "h1_font_size": "2.5rem",
  "h2_font_size": "2rem",
  "h3_font_size": "1.75rem",
  "heading_font_weight": "700",
  "heading_font_family": "Inter",
  "letter_spacing": "0.02em",
  "google_fonts": "Inter:400,700|Playfair Display:700"
}

The framework automatically loads the specified Google Fonts, applies the font stacks globally, and ensures proper fallback chains. You can further refine typography at the section level through the layout builder's inline settings.

Layout and Spacing Controls

The layout builder provides control over container widths, gutter sizes, and section padding. These values are defined as SCSS variables that cascade through the entire template:

// Default layout variables in _variables.scss
$container-max-width: 1140px;
$container-fluid-max-width: 100%;
$grid-gutter-width: 30px;
$section-padding: 60px 0;
$section-margin: 0;
$content-padding: 30px;

In the admin panel, you can adjust these values per breakpoint, allowing you to create layouts that optimize perfectly for mobile, tablet, and desktop viewports without writing media queries by hand.

Advanced SCSS Customization

Creating a Custom Theme Skin

For projects requiring extensive visual changes beyond what the admin panel offers, Helix supports custom theme skins. You create a new SCSS file in the themes directory and import the framework's mixins and variables:

// File: assets/scss/themes/_custom-dark.scss

@import '../variables';
@import '../mixins';

// Override core variables
$primary: #6c5ce7;
$secondary: #a29bfe;
$body-bg: #1a1a2e;
$body-color: #e6e6e6;
$header-bg: #16213e;
$footer-bg: #0f0f1a;
$link-color: #6c5ce7;
$link-hover-color: lighten($primary, 10%);
$border-radius: 12px;

// Custom component styles
.card {
  background: #1e1e3a;
  border: 1px solid rgba(255, 255, 255, 0.05);
  border-radius: $border-radius;
  box-shadow: 0 8px 30px rgba(0, 0, 0, 0.3);
  
  &-header {
    background: rgba(108, 92, 231, 0.1);
    border-bottom: 1px solid rgba(255, 255, 255, 0.05);
  }
}

.btn-primary {
  background: linear-gradient(135deg, #6c5ce7, #a29bfe);
  border: none;
  transition: all 0.3s ease;
  
  &:hover {
    transform: translateY(-2px);
    box-shadow: 0 10px 25px rgba(108, 92, 231, 0.4);
  }
}

// Custom navigation styling
.spp-mega-menu {
  .dropdown-menu {
    background: #1e1e3a;
    border: 1px solid rgba(255, 255, 255, 0.08);
    backdrop-filter: blur(10px);
  }
}

// Custom footer
#sp-footer {
  border-top: 3px solid #6c5ce7;
  background: #0f0f1a;
  padding: 40px 0;
}

To activate this skin, register it in your template's configuration and select it through the admin panel's theme selector. The framework compiles your skin alongside the default styles, applying it as an override layer that preserves all core functionality.

Custom Layout Overrides

Sometimes you need to modify the actual HTML structure of a Joomla component output. Helix uses the standard Joomla template override system but enhances it with framework-specific features. Here is how to create a custom article layout:

<?php
// File: templates/shaper_helixultimate/overrides/layouts/joomla/content/article.php

defined('_JEXEC') or die;

use Joomla\CMS\Layout\LayoutHelper;

// Add Helix-specific article class
$article_class = $this->params->get('helix_article_class', '');
$featured_image = LayoutHelper::render('joomla.content.intro_image', $this->item);

?>

<article class="helix-article ">
  
  <?php if ($featured_image): ?>
    <div class="article-featured-image helix-image-wrapper">
      <?php echo $featured_image; ?>
      <div class="image-overlay"></div>
    </div>
  <?php endif; ?>

  <div class="article-header">
    <h2 class="article-title">
      <a href="<?php echo JRoute::_(ContentHelperRoute::getArticleRoute($this->item->slug, $this->item->catid, $this->item->language)); ?>">
        <?php echo $this->escape($this->item->title); ?>
      </a>
    </h2>
    
    <div class="article-meta helix-meta">
      <span class="meta-author">
        <i class="fas fa-user"></i> <?php echo $this->item->author; ?>
      </span>
      <span class="meta-date">
        <i class="fas fa-calendar"></i> <?php echo JHtml::_('date', $this->item->created, 'F d, Y'); ?>
      </span>
    </div>
  </div>

  <div class="article-body helix-content">
    <?php echo $this->item->introtext; ?>
  </div>

  <?php if ($this->params->get('show_readmore')): ?>
    <div class="article-readmore">
      <a href="<?php echo JRoute::_(ContentHelperRoute::getArticleRoute($this->item->slug, $this->item->catid, $this->item->language)); ?>" class="helix-btn helix-btn-primary">
        <?php echo JText::_('COM_CONTENT_READ_MORE'); ?>
        <i class="fas fa-arrow-right"></i>
      </a>
    </div>
  <?php endif; ?>

</article>

This override demonstrates several Helix-specific patterns: using the framework's helper methods for layout rendering, adding custom CSS classes that integrate with the admin panel's class injection system, and structuring markup to match Helix's component styling conventions. The override file is placed in the template's overrides/ directory following the exact Joomla component path structure.

Custom Module Chrome

Module chrome controls the outer wrapper HTML that surrounds every Joomla module. Helix extends the standard chrome options with its own set that includes built-in styling hooks. You can define custom chrome in your template's templateDetails.xml:

<!-- File: templateDetails.xml -->
<template>
  <!-- ... other configuration ... -->
  
  <modules>
    <module position="helix-custom-top" chrome="helixCard"></module>
    <module position="helix-custom-bottom" chrome="helixCardDark"></module>
  </modules>
</template>

<!-- Corresponding function in template's HTML.php -->
<?php
// File: templates/shaper_helixultimate/html.php

function modChrome_helixCard($module, &$params, &$attribs)
{
    $moduleTag     = 'div';
    $moduleClass   = 'helix-card-module';
    $moduleTitle   = $module->title;
    $moduleContent = $module->content;

    ?>
    <<?php echo $moduleTag; ?> class="<?php echo $moduleClass; ?>">
        <div class="helix-card">
            <?php if ($moduleTitle): ?>
                <div class="helix-card-header">
                    <h4 class="module-title"><?php echo $moduleTitle; ?></h4>
                </div>
            <?php endif; ?>
            <div class="helix-card-body">
                <?php echo $moduleContent; ?>
            </div>
        </div>
    </<?php echo $moduleTag; ?>>
    <?php
}

function modChrome_helixCardDark($module, &$params, &$attribs)
{
    $moduleTag     = 'div';
    $moduleClass   = 'helix-card-module helix-card-dark';
    $moduleTitle   = $module->title;
    $moduleContent = $module->content;

    ?>
    <<?php echo $moduleTag; ?> class="<?php echo $moduleClass; ?>">
        <div class="helix-card helix-bg-dark">
            <?php if ($moduleTitle): ?>
                <div class="helix-card-header helix-card-header-accent">
                    <h4 class="module-title"><?php echo $moduleTitle; ?></h4>
                </div>
            <?php endif; ?>
            <div class="helix-card-body">
                <?php echo $moduleContent; ?>
            </div>
        </div>
    </<?php echo $moduleTag; ?>>
    <?php
}

This approach lets you define semantic wrapper structures that apply consistent styling across all modules in a given position. The chrome functions can access module attributes, allowing dynamic class injection based on backend settings.

Customizing the Mega Menu

Helix's mega menu is one of its most powerful features, and it supports deep customization through both the admin interface and SCSS overrides. The menu builder lets you define column widths, add rich content modules inside dropdowns, and control animation effects. For styling, the menu exposes a comprehensive set of SCSS variables:

// File: assets/scss/components/_mega-menu-custom.scss

// Menu bar variables
$menu-bar-bg: transparent;
$menu-bar-height: 80px;
$menu-item-padding: 15px 20px;
$menu-item-color: #ffffff;
$menu-item-hover-bg: rgba(255, 255, 255, 0.1);
$menu-item-active-border: 3px solid $primary;

// Dropdown variables
$dropdown-bg: #ffffff;
$dropdown-border-radius: 8px;
$dropdown-shadow: 0 15px 40px rgba(0, 0, 0, 0.15);
$dropdown-padding: 30px;
$dropdown-animation: fadeInUp 0.3s ease;

// Custom mega menu styles
.spp-mega-menu {
  .spp-mega-menu-item {
    position: relative;
    
    &::after {
      content: '';
      position: absolute;
      bottom: 0;
      left: 50%;
      transform: translateX(-50%) scaleX(0);
      width: 100%;
      height: $menu-item-active-border;
      background: $primary;
      transition: transform 0.3s ease;
    }
    
    &:hover::after,
    &.active::after {
      transform: translateX(-50%) scaleX(1);
    }
  }

  .spp-mega-menu-dropdown {
    border-radius: $dropdown-border-radius;
    box-shadow: $dropdown-shadow;
    padding: $dropdown-padding;
    
    .mega-column-header {
      font-weight: 700;
      color: $primary;
      margin-bottom: 15px;
      padding-bottom: 10px;
      border-bottom: 2px solid rgba($primary, 0.2);
    }
  }
}

// Mobile menu customization
@media (max-width: 992px) {
  .spp-mega-menu-mobile {
    .menu-toggle {
      width: 30px;
      height: 30px;
      position: relative;
      
      span {
        display: block;
        width: 100%;
        height: 3px;
        background: $menu-item-color;
        border-radius: 2px;
        transition: all 0.3s ease;
        position: absolute;
        
        &:nth-child(1) { top: 0; }
        &:nth-child(2) { top: 50%; transform: translateY(-50%); }
        &:nth-child(3) { bottom: 0; }
      }
      
      &.active {
        span:nth-child(1) {
          transform: rotate(45deg);
          top: 50%;
        }
        span:nth-child(2) {
          opacity: 0;
        }
        span:nth-child(3) {
          transform: rotate(-45deg);
          bottom: 50%;
        }
      }
    }
  }
}

This SCSS demonstrates how to create animated menu indicators, styled dropdown panels with branded column headers, and a custom mobile hamburger toggle animation. All of these styles integrate seamlessly with the existing mega menu JavaScript functionality because they only affect presentation, not behavior.

Custom Section and Row Styling

The Helix page builder uses sections and rows as the primary layout containers. Each section can receive custom CSS classes through the admin interface, enabling you to create highly distinctive page zones. Here is how to define and use custom section styles:

// File: assets/scss/sections/_custom-sections.scss

// Hero section
.section-hero {
  position: relative;
  min-height: 100vh;
  background: linear-gradient(135deg, #{$primary} 0%, #{darken($primary, 20%)} 100%);
  display: flex;
  align-items: center;
  overflow: hidden;
  
  &::before {
    content: '';
    position: absolute;
    top: -50%;
    right: -20%;
    width: 600px;
    height: 600px;
    background: rgba(255, 255, 255, 0.05);
    border-radius: 50%;
    animation: float 20s infinite ease-in-out;
  }
  
  .hero-content {
    position: relative;
    z-index: 2;
    
    h1 {
      font-size: 3.5rem;
      font-weight: 800;
      line-height: 1.2;
      color: #ffffff;
      margin-bottom: 1.5rem;
    }
    
    p {
      font-size: 1.25rem;
      color: rgba(255, 255, 255, 0.85);
      max-width: 600px;
      margin-bottom: 2rem;
    }
  }
}

// Stats section
.section-stats {
  background: #{$body-bg};
  padding: 80px 0;
  
  .stat-card {
    text-align: center;
    padding: 40px 20px;
    border-radius: 12px;
    background: #ffffff;
    box-shadow: 0 5px 25px rgba(0, 0, 0, 0.05);
    transition: transform 0.3s ease, box-shadow 0.3s ease;
    
    &:hover {
      transform: translateY(-8px);
      box-shadow: 0 15px 40px rgba(0, 0, 0, 0.1);
    }
    
    .stat-number {
      font-size: 3rem;
      font-weight: 800;
      color: $primary;
      display: block;
    }
    
    .stat-label {
      font-size: 1rem;
      color: #666;
      text-transform: uppercase;
      letter-spacing: 0.1em;
      margin-top: 10px;
    }
  }
}

// Testimonials section
.section-testimonials {
  background: #f8f9fa;
  padding: 100px 0;
  
  .testimonial-card {
    background: #ffffff;
    border-radius: 16px;
    padding: 40px;
    position: relative;
    box-shadow: 0 10px 30px rgba(0, 0, 0, 0.08);
    
    &::before {
      content: '\201C';
      position: absolute;
      top: 20px;
      left: 30px;
      font-size: 6rem;
      color: rgba($primary, 0.15);
      font-family: Georgia, serif;
      line-height: 1;
    }
    
    .testimonial-text {
      font-size: 1.1rem;
      line-height: 1.8;
      color: #333;
      font-style: italic;
      margin-bottom: 20px;
      padding-top: 20px;
    }
    
    .testimonial-author {
      display: flex;
      align-items: center;
      gap: 15px;
      
      .author-avatar {
        width: 50px;
        height: 50px;
        border-radius: 50%;
        object-fit: cover;
        border: 3px solid $primary;
      }
      
      .author-name {
        font-weight: 700;
        color: #222;
      }
      
      .author-role {
        font-size: 0.85rem;
        color: #888;
      }
    }
  }
}

// Keyframe animations
@keyframes float {
  0%, 100% { transform: translate(0, 0) rotate(0deg); }
  25% { transform: translate(30px, -20px) rotate(5deg); }
  50% { transform: translate(-10px, -40px) rotate(-3deg); }
  75% { transform: translate(-20px, -10px) rotate(2deg); }
}

These section styles can be applied by adding the class names (like section-hero or section-stats) directly in the layout builder's section settings. The framework automatically scopes these styles to their respective sections, preventing leakage to other parts of the page.

Exporting and Importing Theme Presets

One of the most practical aspects of Helix customization is the ability to export your entire theme configuration as a portable JSON file. This allows you to move complete theme setups between installations, back up your design work, or share presets with other developers. The export process captures every setting from the admin panel:

{
  "preset_name": "Corporate Blue Theme",
  "preset_version": "1.0.0",
  "framework_version": "2.0.4",
  "created": "2024-11-15T10:30:00Z",
  "settings": {
    "colors": {
      "primary": "#2563eb",
      "secondary": "#3b82f6",
      "body_bg": "#ffffff",
      "body_text": "#1f2937",
      "header_bg": "#111827",
      "footer_bg": "#111827",
      "link_color": "#2563eb",
      "link_hover": "#1d4ed8"
    },
    "typography": {
      "body_font": "Inter",
      "heading_font": "Inter",
      "body_size": "16px",
      "h1_size": "2.25rem",
      "h2_size": "1.875rem",
      "h3_size": "1.5rem",
      "line_height": "1.65",
      "letter_spacing": "0.01em"
    },
    "layout": {
      "container_width": "1200px",
      "gutter": "30px",
      "section_padding": "60px",
      "header_mode": "sticky",
      "header_height": "80px",
      "logo_position": "left",
      "menu_alignment": "right"
    },
    "sections": {
      "hero": {
        "background": "linear-gradient(135deg, #2563eb, #1d4ed8)",
        "padding": "120px 0",
        "text_color": "#ffffff"
      }
    },
    "custom_css": "",
    "custom_js": ""
  }
}

To import a preset, you upload this JSON through the Helix admin panel's import tool. The framework validates the structure, applies all settings atomically, and regenerates the necessary CSS. This makes staging-to-production deployments remarkably smooth — you develop the theme on a staging environment, export the finalized preset, and import it on the live site in a single operation.

Best Practices for Helix Customization

Use SCSS Overrides, Never Core Edits

Always place custom styles in the assets/scss/themes/ directory or create a dedicated override SCSS file. Core files in the helix/ directory are subject to change during framework updates. By keeping customizations in the designated override areas, you ensure your work is portable and update-safe. A common pattern is to create a _custom-overrides.scss file that imports framework variables and then applies all project-specific modifications:

// File: assets/scss/themes/_custom-overrides.scss
// This file is loaded last, ensuring all overrides take precedence

@import '../variables';
@import '../mixins';

// Project-specific overrides organized by component
// ---- Header ----
#sp-header { /* custom header styles */ }

// ---- Navigation ----
.spp-mega-menu { /* custom nav styles */ }

// ---- Articles ----
.helix-article { /* custom article styles */ }

// ---- Footer ----
#sp-footer { /* custom footer styles */ }

Document Your Customizations

Maintain a CUSTOMIZATION.md file in your template's root directory that documents every customization point. Include the admin panel settings, SCSS modifications, override files created, and any custom module chrome defined. This documentation becomes invaluable when handing off projects to other developers or when revisiting a site months later for maintenance. Document the reasoning behind each customization decision — this context helps future maintainers understand whether a particular override is essential or can be adjusted.

Version Control Your Template Directory

Treat your Helix template directory as a proper software project. Initialize a Git repository inside the template folder and track changes to SCSS files, overrides, and configuration exports. Exclude the compiled CSS and JS from version control — these are build artifacts that can be regenerated. Your .gitignore should look something like this:

# Helix template gitignore
assets/css/
assets/js/
node_modules/
dist/
*.min.css
*.min.js
.sass-cache/
.DS_Store

Commit your source SCSS, override PHP files, and exported preset JSONs. This gives you a complete history of design changes and makes collaboration with other developers straightforward.

Test Customizations Across All Breakpoints

Helix's responsive system is powerful but can produce unexpected results when custom styles interact with the framework's built-in breakpoint logic. Always test your customizations at every defined breakpoint — typically 576px, 768px, 992px, and 1200px. Pay special attention to custom section padding and mega menu behavior on mobile devices. The framework's mobile menu system relies on specific class toggles; ensure your custom styles don't interfere with these mechanisms.

Leverage the Preset System for Client Projects

Build a library of proven presets that you can adapt for new projects. Start with a base preset that includes your agency's default typography stack, color palette approach, and common layout patterns. For each new client, fork the base preset and customize it incrementally. This approach ensures consistency across your portfolio while dramatically reducing the time needed to set up new themes. Over time, your preset library becomes a valuable intellectual asset that differentiates your work in the marketplace.

Performance Considerations

Customization can impact page performance if not handled carefully. Every additional SCSS rule you add contributes to the final stylesheet size. Helix mitigates this through its build process, which minifies and combines stylesheets, but you should still practice restraint. Avoid deeply nested selectors that generate bloated CSS output. Use Helix's built-in utility classes wherever possible instead of writing custom rules for common patterns like spacing, text alignment, or background colors. The framework includes a comprehensive utility class system that covers most layout needs without adding custom CSS weight.

When adding custom fonts through Google Fonts, limit the number of font weights and families you load. Each additional font file adds network requests and parsing time. Stick to a maximum of two font families with essential weights only — typically regular (400), medium (500), and bold (700) for body text, plus one decorative weight for headings if needed. Helix's font loading uses the recommended display=swap parameter, ensuring text remains visible during font loading.

Conclusion

Helix theme customization represents a sweet spot between developer control and administrative convenience. The framework's layered architecture — admin panel settings feeding SCSS variables, override files allowing surgical markup changes, and the preset system enabling portable theme configurations — gives you a complete toolkit for crafting distinctive, maintainable Joomla themes. By adhering to the override pattern, documenting your work, and building a library of reusable presets, you transform Helix from a mere template framework into a professional design system that accelerates your entire development workflow. The time invested in learning its customization pathways pays dividends across every subsequent project, turning what was once a tedious per-site styling exercise into a streamlined, repeatable process that consistently delivers polished, branded experiences.

🚀 Need a reliable AI agent for your project?

Deploy Hermes Agent in 10 minutes. Managed hosting, zero DevOps.

Get Started — $23.99/mo
← Back to all articles