The Helium Theme for Gantry 5: What It Includes and How to Set It Up

If you install the Gantry 5 framework and want a theme to start from, Helium is the one the official documentation reaches for. The installation guide calls it "a great free default theme for Gantry 5", and the Grav version of the theme describes itself in its own metadata as the "Default Gantry 5 theme." This guide covers what Helium is, what comes inside the package, how to install and activate it on each platform, and how to customise and update it without losing your work.

Everything here is drawn from the Gantry documentation, the Gantry downloads page and the Helium source files in the public Gantry 5 repository. Links are listed at the bottom. Version numbers change, so check the downloads page before you install.

What Helium is

Gantry 5 is a theming framework, not a theme. The documentation explains that the framework is independent of any theme, and that a Gantry-powered theme relies on the framework to work. Helium is one of those themes. It is built and distributed by the Gantry team alongside an older, simpler theme called Hydrogen.

The names are deliberate. The introduction to the documentation notes that Gantry uses atomic names for its features, such as the Hydrogen and Helium templates, and the same idea runs through terms like Particles and Atoms.

At the time of writing, the Gantry downloads page lists Helium at version 5.6.4, the same version number as the framework itself, with separate packages for each platform:

grav-tpl_g5_helium_v5.6.4.zip for Grav (the page lists Grav 1.7.25+ for this release)
joomla-tpl_g5_helium_v5.6.4.zip for Joomla (listed for Joomla 5.0+)
wordpress-tpl_g5_helium_v5.6.4.zip for WordPress (listed for WordPress 5.2+)

On the same page the Helium packages are roughly 4 MB each, while the Hydrogen packages are well under 1 MB. That is a useful hint about the difference: Hydrogen is a bare starting point, while Helium ships with more styling, presets and sample layouts.

What ships inside Helium

Because Gantry 5 is open source, you can look at exactly what the theme contains. The Helium folder in the Gantry 5 repository is split into a common folder shared by all platforms and separate grav, joomla and wordpress folders. In the shared part you will find:

Style presets. The file gantry/presets.yaml defines six presets, preset1 to preset6. Each one sets a preview image, a pair of display colours and a block of style values such as the base background, the text colour and accent colours.
Layout presets. The layouts folder contains default.yaml and home_-_particles.yaml, which you can load as starting points in the Layout Manager, plus _body_only.yaml, _error.yaml and _offline.yaml. The underscore files line up with the special-purpose pages Gantry handles, such as error and offline pages.
Theme particles. Beyond the particles that come with the framework, Helium adds its own: Content Cubes, Content Tabs, Copyright, Horizontal Menu, Owl Carousel and To Top. Each is defined by a YAML file (its settings form) and a Twig file (its markup), following the same pattern the documentation describes for custom particles.
Style settings. The blueprints/styles folder holds one YAML file per group of settings in the Styles panel, including base, accent, font, link, menu, header, navigation, intro, features, utility, above, expanded, testimonials, footer, offcanvas and breakpoints.
SCSS. Helium's stylesheets live in scss, with separate partials for sections such as the header, navigation, main area, sidebar, footer and off-canvas menu.

The Grav version's blueprints.yaml also declares its dependencies: Grav 1.7 or later and the Gantry 5 plugin at version 5.5 or later.

Installing Helium

The order matters on every platform. The installation guide says the Gantry 5 framework should be installed before a Gantry theme, because the theme is not much use without it.

Joomla

Install the Gantry framework package through Extensions, Extensions Manager, Install, then install the Helium template package the same way. The documentation says the process is the same for both; only the file differs. To make it the active site template, go to the Template Manager, select the Gantry template and choose Default. The documentation notes that some Gantry templates set themselves as default automatically.

WordPress

Install and activate the Gantry 5 Framework plugin first. Then go to Appearance, Themes, Add New, Upload Theme, choose the Helium zip file and select Install Now. You can activate it straight from the confirmation screen or later from Appearance.

Grav

Grav gives you three routes, and the documentation uses Helium as its worked example for all of them:

Admin panel. With the Admin plugin installed, go to Admin, Themes, Add, find Helium and install it.
File system. Unzip the theme into user/themes. This creates user/themes/g5_helium.
Command line. From the root of the site, run bin/gpm install helium.

To activate it, either select Activate under Admin, Themes, or edit user/config/system.yaml and set the theme under pages:

pages:
  theme: g5_helium

Customising Helium with the Styles panel

Most visual changes happen in Gantry's Styles panel rather than in code. The documentation describes it as a one-stop shop for changing how the theme looks for a specific outline. It works in three layers:

Preset selector. Pick one of Helium's presets to switch the colour palette and related style values in one step.
Theme-specific settings. Refine individual values in the sections defined by Helium's style blueprints. In a non-default outline these settings appear faded until you choose to override the default, and unchecking the box returns a setting to the default.
Configuration styles. Set responsive breakpoints and some menu options for the outline.

The Save Styles button saves the settings and recompiles the CSS, so you do not need to press Recompile CSS separately.

If you want your own preset, the documentation recommends copying the theme's existing presets.yaml and saving the edited copy in the custom area: custom/gantry/ on Joomla and WordPress, or user/data/gantry5/themes/THEME_DIR/gantry/ on Grav. The new file replaces the theme's preset list, so keep any presets you still want. The documentation also points out that preset variables are defined by the theme, not by Gantry, so a new variable has no effect until your own SCSS uses it.

Keeping customisations safe

Gantry stores what you change in the admin, such as settings, layouts and custom CSS, in a custom directory rather than in the theme's own files. The documentation gives these locations:

Joomla: /templates/THEME_NAME/custom/
WordPress: /wp-content/themes/THEME_NAME/custom/
Grav: user/data/gantry5/themes/THEME_DIR/

Because this data is stored as flat files, the documentation says it can be moved to another Gantry theme or even another platform, though some reconfiguration may be needed if a particle exists in one theme and not the other. On Joomla, outline ID numbers must match the folder numbers in custom/config when you move settings across.

Updating Helium

The update guide recommends a full backup before any theme update, including the database where there is one and the theme's directory. It also advises keeping track of any theme files you edited directly instead of through the custom directory, since those can revert.

Joomla: update Gantry before the template, because a template update may depend on new framework features. Use Extensions, Manage, Update, or upload the newer package through Install.
WordPress: upload the new Helium package through Appearance, Themes, Add New, Upload Theme, then activate it, clear the Gantry cache and test the site.
Grav: update from the Themes section or the Dashboard of the Grav Admin, or run bin/gpm update helium from the site root and confirm with Y.

Is Helium the right starting point?

Helium suits site builders who want a finished-looking base with several colour presets and sample layouts, and who prefer to work in the Gantry admin rather than in code. If you want to build a design from close to nothing, the lighter Hydrogen theme may be the more practical base. Either way, keep your changes in the custom directory and the theme can be updated without starting over.

Sources

Gantry 5 documentation, Installation: https://docs.gantry.org/gantry5/basics/installation
Gantry 5 documentation, Introduction: https://docs.gantry.org/gantry5/basics/introduction
Gantry 5 documentation, Styles: https://docs.gantry.org/gantry5/configure/styles
Gantry 5 documentation, Creating Style Presets: https://docs.gantry.org/gantry5/advanced/creating-style-presets
Gantry 5 documentation, Updating Themes: https://docs.gantry.org/gantry5/basics/updating-themes
Gantry 5 documentation, Moving Custom Settings Between Themes: https://docs.gantry.org/gantry5/tutorials/moving-between-themes
Gantry 5 documentation, Creating a New Particle: https://docs.gantry.org/gantry5/advanced/creating-a-new-particle
Gantry downloads (versions, package names, platform minimums, sizes): https://gantry.org/downloads
Gantry 5 source, Helium theme folder: https://github.com/gantry/gantry5/tree/develop/themes/helium
Gantry 5 source, Helium style presets: https://raw.githubusercontent.com/gantry/gantry5/develop/themes/helium/common/gantry/presets.yaml
Gantry 5 source, Helium Grav blueprint (description and dependencies): https://raw.githubusercontent.com/gantry/gantry5/develop/themes/helium/grav/blueprints.yaml

Gantry 5 on Grav: Framework, Themes and Safe Customisation