Skip to main content

Create a theme from scratch

This guide walks you through creating your first Shoplazza theme from scratch. By the end, you'll have a working theme with a layout, a home page, a navigation menu, and a product detail page.

What you'll learn​

  • The basic directory structure of a Shoplazza theme
  • How to create a layout, templates, sections, and snippets
  • How to build a dynamic navigation menu and a product detail page
  • How to upload and preview your theme

Prerequisites​

  1. A Shoplazza store — you can't develop a theme without one.
  2. A text editor, or the built-in Shoplazza theme editor.
  3. Basic knowledge of HTML, CSS, JavaScript, and Liquid — Shoplazza themes are built with these technologies.

Step 1: Set up the directory structure​

Create a new folder for your theme with the following structure:

my-new-theme/
├── assets/
├── config/
│   └── settings_data.json
├── layout/
│   └── theme.liquid
├── sections/
│   ├── header.liquid
│   └── product-template.liquid
├── snippets/
│   └── navigation.liquid
└── templates/
    ├── index.liquid
    └── product.liquid

For a complete overview of all directories and their roles, see Theme architecture overview.

tip

You can also scaffold a complete directory structure in seconds with shoplazza theme init, which clones Nova 2023. Nova 2023 is a full-featured reference theme, so its structure is richer than the minimal layout built by hand here. See Develop with Shoplazza CLI.

Step 2: Create the layout file​

The layout file is the HTML shell that wraps every page. Create layout/theme.liquid:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>{{ shop.name }} - {{ page.title }}</title>
  {{ content_for_header }}
</head>
<body>
  {% section 'header' %}

  <main>
    {{ content_for_layout }}
  </main>

  <footer>
    <p>&copy; {{ 'now' | date: "%Y" }} {{ shop.name }}</p>
  </footer>

  {{ content_for_js }}
</body>
</html>

{{ content_for_header }} and {{ content_for_js }} load scripts required by Shoplazza. {{ content_for_layout }} is where template content gets injected. The {% section 'header' %} tag renders the header section you'll create in Step 5. To learn more, see Theme layouts.

Step 3: Create the home page template​

Create templates/index.liquid — this is what renders on your store's home page:

<section>
  <h2>Welcome to {{ shop.name }}</h2>
  <p>This is your first Shoplazza theme.</p>
</section>

Step 4: Create the config file​

Create config/settings_data.json with a minimal valid structure:

{
  "current": {}
}

To learn more about theme configuration, see Theme config.

Step 5: Create a navigation menu​

Build a dynamic header navigation that reads from the store's linklist configuration and supports dropdown submenus.

First, create the header section sections/header.liquid:

<header class="site-header">
  <h1 class="site-title">{{ shop.name }}</h1>

  <nav class="main-navigation">
    {% include 'navigation', links: linklists.main-menu.links %}
  </nav>
</header>

This includes a snippet named navigation and passes the links from the main-menu linklist to it.

Next, create the navigation snippet snippets/navigation.liquid:

<ul class="menu">
  {% for link in links %}
    <li class="menu-item">
      <a href="{{ link.url }}">{{ link.title }}</a>
      {% if link.links %}
        <ul class="submenu">
          {% for sublink in link.links %}
            <li class="submenu-item">
              <a href="{{ sublink.url }}">{{ sublink.title }}</a>
            </li>
          {% endfor %}
        </ul>
      {% endif %}
    </li>
  {% endfor %}
</ul>

The snippet loops through each link in the linklist. If a link has child links, it renders a submenu. To learn more about snippets, see Snippets.

Step 6: Create a product detail page​

Build a section that displays product information and offers merchant-configurable settings through the theme editor.

Create the product section sections/product-template.liquid:

{% if product %}
  <h1>{{ product.title }}</h1>
  <p>{{ product.description }}</p>
  {% if section.settings.show_vendor %}
    <p>{{ product.vendor }}</p>
  {% endif %}
  <img src="{{ product.featured_image | img_url: '480x480' }}" alt="{{ product.featured_image.alt | escape }}">
  <p>{{ product.price | money }}</p>
{% else %}
  <p>This product does not exist.</p>
{% endif %}

{% schema %}
{
  "name": "Product template",
  "settings": [
    {
      "type": "checkbox",
      "id": "show_vendor",
      "label": "Show vendor",
      "default": true
    }
  ]
}
{% endschema %}

The {% schema %} block defines a show_vendor toggle that merchants can control in the theme editor. For all available setting types, see Input settings.

Then create the product template templates/product.liquid to render the section on product pages:

{% section 'product-template' %}

The product object inside the section automatically refers to the current product being viewed.

Step 7: Upload and preview your theme​

  1. Compress your my-new-theme/ folder into a .zip file.
  2. In your Shoplazza admin, go to Online Store → Themes.
  3. Click Upload theme and select the .zip file.
  4. After the upload completes, click Actions → Preview next to your theme.

Your browser opens a new tab showing your theme with a navigation menu, a home page, and product pages. In the theme editor, you can assign a linklist to the main-menu and toggle the Show vendor setting on product pages.

tip

For a more streamlined development workflow using Shoplazza CLI with live preview and hot reload, see the CLI-based tutorial.

Next steps​

Now that you have a working theme, explore these topics to build it out: