Skip to content

A useful list of helpers for Shopify theme development.

License

Notifications You must be signed in to change notification settings

odestry/theme-development-helpers

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

53 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Theme Development Helpers

PRs Welcome CI Discord Shield

Usage | Tools | Contributing | About | License

A growing collection of useful helpers and fully functional, ready-made utils for Shopify theme development. If you make a snippet that is generic enough to be useful to others, think about CONTRIBUTING.

Usage

Copy the code from the snippet you want to use and paste it into your theme's /snippets folder. Then include the snippet in your theme sections.

{% render 'snippet-name' %}

You can also use our theme starter template to quickly preview these helpers. See odestry/theme-starter.

Theme app extensions

For theme app extensions, you can do the same thing as above, but instead of sections, you include the snippet in your app blocks.

Index

You can navigate these snippets by using the table below.

Category Snippet Description
Tools Development screen indicator A simple indicator that shows which viewport size you are in. Useful for debugging and development.
Tools Metaobject detector A way to detect the current metaobject on the metaobject template without relying on dynamic ressources.
Meta Social share A small snippet to render all necessary meta tags for social sharing and page previews on socials.
UI Image A powerful, less opinionated image snippet built on top of evergreen web technologies for Shopify storefronts.
UI Shop pay button Pure liquid dynamic Shop pay button for express checkout.
Schemas Schema website Renders the schema.org website JSON-LD for Site Name.
Schemas Schema organization Renders the schema.org JSON-LD for Brand and Organization.
Schemas Schema article Renders the schema.org JSON-LD for a blog post or an article.

Tools

These are tools that can be used to enhance the theme development experience.

Development screen indicator

A simple indicator that shows which viewport size you are in. Useful for debugging and development.

Built with Tailwind CSS and can be added on the theme.liquid layout file.

Copy code from this file.

{% liquid
  if settings.enable_development_mode
    render 'development-screen-indicator'
  endif
%}

An example of a setting to enable the development screen indicator on demand:

{
  "type": "checkbox",
  "id": "enable_development_mode",
  "label": "Enable development mode",
  "default": false
}

Metaobject detector

This must be used inside a metaobject template. It detects the current metaobject and renders its properties or other metaobjects if it has any.

Copy code from this file.

{% render 'metaobject-detector' %}

Learn more about metaobject templates here.

Meta

These are snippets that render meta tags to enhance the storefront with additional information.

Social share

A small snippet to render all necessary meta tags for social sharing and page previews on socials.

Copy code from this file.

{% render 'social-share' %}

You can also check Shopify recommandations on social sharing.

Debugging previews

To debug your social share previews, you can use the Facebook Sharing Debugger and the Twitter Card Validator.

Schemas

These JSON-LD snippets are based on the Schema.org vocabulary and are used to improve the display of your pages on search engines.

Schema website

Renders the schema.org website JSON-LD for Site Names.

Copy code from this file.

{% render 'schema-website' %}

You can check the Google Structured Data Docs for more information.

Schema organization

Renders the schema.org JSON-LD for Brand and Organization. Must be used on all templates.

Copy code from this file.

{% render 'schema-organization' %}

You can check the Google Structured Data Docs for more information about this schema.

Schema article

Renders the schema.org JSON-LD for Blog post and article. Must be used on article cards or templates.

Copy code from this file.

{% render 'schema-article' article: block.settings.article %}

You can check the Google Structured Data Docs for more information about this schema.

Debugging structured data

To debug your structured data, you can use the Google Structured Data Testing Tool and the Google Rich Results Test.

UI

These are user interface snippets that are optimized and can be reused within your theme.

Image

A powerful, less opinionated image snippet built on top of evergreen web technologies for Shopify storefronts.

Copy code from this file.

Check more informations about this image snippet as well as a preview of the snippet in action here.

Arguments

The image has a very easy-to-understand sample API, and all of these arguments are optional:

  • image: The image object. This can be a product image or a media object of type image as well.
  • class: A string of classes, same as the class HTML attribute.
  • lazyload: By default, the snippet is eagerly loaded. If you want to lazyload the image, you can set this boolean parameter to true.
  • width: This is the maximum width of the srcset. In some cases, it makes sense to load a smaller srcset if the image is small.
  • alt: You can set a custom alt text. By default, Shopify uses the product title as the alt text if the image is associated with a product.
  • placeholder: The placeholder handle that is defined by Shopify. If you want to set other types of placeholders, check the Shopify documentation.

Examples

There are many different ways to use this snippet. The easiest one is just by calling it with a render tag.

Displaying a placeholder

If the image is blank or doesn't have any image object, it displays a placeholder like the following:

{% render 'image' %}

You can also pass a placeholder names handle to the snippet:

{% render 'image', placeholder: 'product-apparel-4' %}

You can check a list of all the available placeholders illustrations here.

Displaying product featured image

You can easily display a product image with the following:

{% render 'image' with product.featured_image %}

Which is the same as:

{% render 'image', image: product.featured_image %}

It also accepts multiple arguments at once:

{% render 'image' with product.featured_image,
  alt: product.title,
  class: 'aspect-square object-center',
  lazyload: true,
  placeholder: 'hero-apparel-3'
%}
Lazyload images in a product grid

You can lazyload images if the grid is made of different product cards, for example, and set the lazyload attribute based on the current position of the image on the grid.

{% liquid
  assign lazyload = false
  for product in collection.products
    if forloop.index > 6
      assign lazyload = true
    endif

    render 'image' with product.featured_image, lazyload: lazyload
  endfor
%}
Set aspect ratio of the image

We recommend using the native browser aspect ratio CSS rule. An example would be to create a class for each of these rules and pass it via the class argument like the following:

{% render 'image' with product.featured_image, class: 'aspect-square' %}

If you don't use tailwind, you can set this class on the image instead:

.image {
  display: block;
  vertical-align: middle;
  aspect-ratio: auto;
  height: auto;
  object-fit: cover;
  max-width: 100%;
}

And then set this on the snippet class default value:

  ...
  assign class = 'image ' | append: class
  ...

Shop pay button

Pure liquid dynamic Shop pay button for express checkout.

Copy code from this file.

{% render 'shop-pay-button' variant: variant: product.selected_or_first_available_variant %}

This snippet is based on the Shopify web component.

Contributing

We'd love your help! Please read our contributing guide to learn about our development process, how to propose bug fixes and improvements.

About

Odestry isn't just a community; it's a group of dedicated folks all aiming to build better commerce together. Our mission is to create a supportive and open space where anyone, regardless of experience, can connect, learn, and grow. Here, you'll get inspired, have real talks, and find plenty of resources and open source tools to help you build. Whether you're looking to network, find opportunities, or just have meaningful conversations, join us and be part of a community that values authenticity, collaboration, and innovation. Learn more.

License

Copyright (c) 2024-present Odestry. See LICENSE for further details.