Skip to main content
Eaglecart’s theme system gives you precise control over every layer of the storefront. You can define merchant-friendly settings that appear in the no-code Theme Editor, build reusable sections with their own configuration schemas, serve optimised CSS and JavaScript through the asset pipeline, and support multiple languages with a straightforward translation API — all without leaving the Liquid template layer.
Never edit your active (live) theme directly when testing new features. Always duplicate the theme first — go to Online Store → Themes → [your theme] → ⋯ → Duplicate — develop on the copy, then publish once you’ve verified everything works as expected.
Use the Eaglecart Theme CLI (eaglecart-cli) to sync theme files between your local machine and the admin. Run eaglecart-cli theme pull to download the current theme, edit files in your editor of choice, and push changes back with eaglecart-cli theme push. The CLI also supports a --watch flag to sync changes automatically as you save.

Theme Settings Schema

Themes support a settings_schema.json file that defines merchant-editable settings. These settings appear as form controls inside Online Store → Themes → Customize, letting merchants adjust colours, logos, typography, and layout without touching any code. The schema is an array of setting group objects. Each group has a name (the section heading in the editor UI) and a settings array of individual setting definitions.
/config/settings_schema.json
Access any setting value in Liquid templates using the settings object and the setting’s id:
Accessing settings in Liquid
Eaglecart supports the following setting types: text, textarea, number, range, color, font_picker, image_picker, url, select, checkbox, radio, and header (label-only, no value). Refer to the Theme Settings Schema reference for a full list of properties each type accepts.

Creating a Custom Section

Sections are Liquid files in /sections/ that combine markup with a {% schema %} block. Merchants can add, reorder, and configure sections in the Theme Editor; you control exactly which settings are available.
1

Create the section file

Add a new .liquid file inside the /sections/ directory of your theme. Name it with a lowercase, hyphenated slug that describes the section’s purpose — for example, /sections/promo-banner.liquid.
2

Add your Liquid markup

Write the HTML and Liquid code that renders the section. Use section.settings.<id> to access the values merchants configure in the Theme Editor.
3

Define the section schema

Append a {% schema %} block to the bottom of the file. The schema is a JSON object that declares the section’s settings, presets, and optional block types. The schema block must be the last tag in the file.
4

Include the section in a template

Reference the section in any template file using the {% section %} tag. Pass the filename without the .liquid extension.
Render a section statically
To make a section dynamically addable from the Theme Editor, add it to the template’s JSON wrapper file (e.g. templates/index.json) instead.
Here is a complete minimal section example that renders a promotional banner with a merchant-editable heading, subheading, and background colour:
/sections/promo-banner.liquid

Using the Asset Pipeline

All CSS, JavaScript, image, and font files placed in the /assets/ directory are served through Eaglecart’s CDN-backed asset pipeline. Reference them in Liquid using the asset_url filter.

Stylesheets and scripts

Referencing assets in Liquid

Minification

Eaglecart automatically serves the minified version of any file whose name contains .min. — for example, theme.min.js or main.min.css. Keep both the source and minified versions in /assets/ during development, and reference the .min. file in production templates for faster load times.
Conditionally use the minified build
Files in /assets/ are hashed at deploy time for cache busting. Never hard-code the full CDN URL in your templates — always use asset_url so Eaglecart can append the correct hash query string automatically.

Translation / i18n

Eaglecart’s built-in translation system lets you maintain a single set of Liquid templates that render in multiple languages. Add translation strings to locale files in /locales/ and output them in templates using the t filter.

Adding translation strings

Create or edit the appropriate locale file. Use a nested JSON structure to organise strings by feature area:
/locales/en.json
Add an equivalent file for each additional locale your store supports — for example, /locales/fr.json for French:
/locales/fr.json

Using translations in Liquid

Reference a translation key in any template using the t filter with the dot-separated path to the string:
Using the t filter
If a key is missing from the active locale file, Eaglecart automatically falls back to en.json. If the key is also missing there, the raw key path is rendered — a useful signal during development that a translation string needs to be added.
Eaglecart supports the standard one / other pluralisation convention. Define both forms in your locale file and pass the count variable to the t filter:
/locales/en.json (pluralisation)
Plural in Liquid
For right-to-left locales such as Arabic or Hebrew, add "rtl": true to the locale file’s root object. Eaglecart adds dir="rtl" to the <html> element automatically when a RTL locale is active, so your CSS dir selectors work without any extra Liquid logic.
/locales/ar.json (RTL)