Build Fluid Themes

Build fast, flexible themes at scale using Liquid templating language, JSON sections, and modern web technologies including HTML, CSS, and JavaScript.

Build a new theme - Create a new theme based on Fluid's root themes (Fluid, Vox, or Base)

Customize a theme - Update the look and feel of an existing theme to tailor it to your company's unique brand and requirements

Getting Started
Key Concepts
Architecture
Layouts
Templates
Sections
Blocks
Settings
Config
Locales
Best Practices
Migration Guide

Getting Started

Overview

Fluid themes are a package of template files, building blocks, and supporting assets that define how your company's pages look and function. The theme system provides multiple levels of customization, from simple CSS variable changes to complete template overrides.

Quick Start

Choose a Root Theme: Select from Fluid, Vox, or Base themes
Clone for Customization: Create a company-specific copy
Configure Variables: Set brand colors, fonts, and spacing
Customize Templates: Override specific page layouts as needed
Publish: Activate your theme for all users

The theme system handles the technical implementation behind the scenes, allowing you to focus on design and customization.

Key Concepts

Themes vs Application Themes

Legacy Themes - Simple theme selection system for basic switching Application Themes - Full-featured system with template management, versioning, and customization

Theme Hierarchy

Root Themes: Platform-provided base themes (fluid, vox, base)
Company Themes: Company-specific themes that clone and customize root themes
Template Inheritance: Company themes can override specific templates while inheriting others

Template Types

Templates in Fluid themes handle different content types and page layouts:

Template Type	Purpose	Examples
Content Templates	Render specific content items	`product`, `medium`, `library`
Page Templates	Handle page types	`home_page`, `shop_page`, `cart_page`
Layout Components	Provide page structure	`navbar`, `footer`, `layouts`
Structural Components	Reusable template parts	`sections`, `components`, `config`

Architecture

Theme-Company Relationships

Template Resolution Priority

URL Parameter Override - ?template_id=123 (highest priority)
Content-Specific Assignment - Individual content items with assigned templates
Company Theme Default - Default templates in company's active theme
Root Theme Fallback - Inherit from root theme if company theme lacks template

Request Flow

User Request → Controller → Template Resolution → Variable Population → Rendering → Response

Layouts

Layouts provide the structural wrapper for your content, defining the overall page structure including HTML document structure, navigation, and footer elements.

Layout Structure

<!DOCTYPE html>
<html lang="{{ request.locale.iso_code }}">
<head>
  <meta charset="utf-8">
  <title>{{ page_title | default: company.name }}</title>
  <meta name="viewport" content="width=device-width, initial-scale=1">
  
  <!-- Theme stylesheets with CSS variables -->
  <style>
    :root {
      --primary-color: {{ theme.variables.primary_color }};
      --font-family: {{ theme.variables.font_family }};
    }
  </style>
  
  {{ theme.global_stylesheet_with_variables | raw }}
  {{ theme.custom_stylesheet | raw }}
</head>
<body>
  <!-- Navigation -->
  
  <!-- Main content area -->
  {{ content_for_layout }}
  
  <!-- Footer -->
  
  <!-- JavaScript -->
  <script src="{{ 'theme.js' | asset_url }}"></script>
</body>
</html>

Layout Assignment

Templates can specify their layout using:

Liquid Templates:


<!-- Template content -->

JSON Templates:

{
  "layout": "theme",
  "sections": {
    // section definitions
  }
}

Custom Layouts

Create specialized layouts for different page types:

<!-- layouts/minimal.liquid -->
<!DOCTYPE html>
<html>
<head>
  <title>{{ page_title }}</title>
  {{ theme.global_stylesheet_with_variables | raw }}
</head>
<body class="minimal-layout">
  {{ content_for_layout }}
</body>
</html>

Templates

Templates define the structure and content for specific page types. Fluid supports both Liquid and JSON template formats.

Liquid Templates

Traditional server-side templating using Liquid syntax:


  Product page template


<article class="product-page">
  <header class="product-header">
    <h1>{{ product.name }}</h1>
    <div class="product-price">
      {{ product.price | money }}
    </div>
      <div class="product-tags">
        {{ product.tags | join: ', ' }}
      </div>
  </header>

  <div class="product-gallery">
      <img src="{{ image.url | img_url: '600x400' }}" 
           alt="{{ image.alt }}" />
  </div>

  <div class="product-description">
    {{ product.description }}
  </div>

    <button class="btn-purchase" data-product-id="{{ product.id }}">
      {{ 'products.add_to_cart' | t }}
    </button>
</article>