{"id":13942145,"url":"https://github.com/odestry/theme-development-helpers","last_synced_at":"2025-09-02T16:35:06.451Z","repository":{"id":189610652,"uuid":"680956852","full_name":"odestry/theme-development-helpers","owner":"odestry","description":"A useful list of helpers for Shopify theme development.","archived":false,"fork":false,"pushed_at":"2024-08-11T11:00:18.000Z","size":102,"stargazers_count":68,"open_issues_count":2,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-07-18T14:05:53.917Z","etag":null,"topics":["liquid","shopify","theme"],"latest_commit_sha":null,"homepage":"","language":"Liquid","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/odestry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-21T00:05:32.000Z","updated_at":"2025-05-24T12:53:00.000Z","dependencies_parsed_at":"2023-11-21T14:49:26.598Z","dependency_job_id":"b9d5cf53-0312-4f66-8e81-66f332017983","html_url":"https://github.com/odestry/theme-development-helpers","commit_stats":null,"previous_names":["odestry/theme-development-helpers"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/odestry/theme-development-helpers","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odestry%2Ftheme-development-helpers","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odestry%2Ftheme-development-helpers/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odestry%2Ftheme-development-helpers/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odestry%2Ftheme-development-helpers/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/odestry","download_url":"https://codeload.github.com/odestry/theme-development-helpers/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/odestry%2Ftheme-development-helpers/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266071519,"owners_count":23871940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["liquid","shopify","theme"],"created_at":"2024-08-08T02:01:43.307Z","updated_at":"2025-07-20T05:32:08.218Z","avatar_url":"https://github.com/odestry.png","language":"Liquid","funding_links":[],"categories":["Liquid"],"sub_categories":[],"readme":"# Theme Development Helpers\n\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat\u0026colorA=338fbb\u0026colorB=1c1c1c\u0026logoColor=ffffff)](https://github.com/odestry/.github/blob/main/CONTRIBUTING.md)\n[![CI](https://img.shields.io/github/actions/workflow/status/odestry/theme-development-helpers/ci.yml?style=flat\u0026label=CI\u0026colorA=338fbb\u0026colorB=1c1c1c\u0026logoColor=ffffff)](https://github.com/odestry/theme-development-helpers/blob/main/.github/workflows/ci.yml)\n[![Discord Shield](https://img.shields.io/discord/983602196493004820?style=flat\u0026colorA=338fbb\u0026colorB=1c1c1c\u0026label=discord\u0026logo=discord\u0026logoColor=ffffff)](https://odestry.com/community)\n\n[Usage](#usage) |\n[Tools](#tools) |\n[Contributing](#contributing) |\n[About](#about) |\n[License](#license)\n\nA 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](#contributing).\n\n## Usage\n\nCopy 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.\n\n```liquid\n{% render 'snippet-name' %}\n```\n\nYou can also use our theme starter template to quickly preview these helpers. See [odestry/theme-starter](https://github.com/odestry/theme-starter).\n\n### Theme app extensions\n\nFor theme app extensions, you can do the same thing as above, but instead of sections, you include the snippet in your app blocks.\n\n### Index\n\nYou can navigate these snippets by using the table below.\n\n| Category | Snippet | Description |\n| --- | --- | --- |\n| [Tools](#tools) | [Development screen indicator](#development-screen-indicator) | A simple indicator that shows which viewport size you are in. Useful for debugging and development.\n| [Tools](#tools) | [Metaobject detector](#metaobject-detector) | A way to detect the current metaobject on the metaobject template without relying on dynamic ressources.\n| [Meta](#meta) | [Social share](#social-share) | A small snippet to render all necessary meta tags for social sharing and page previews on socials. |\n| [UI](#ui) | [Image](#image) | A powerful, less opinionated image snippet built on top of evergreen web technologies for Shopify storefronts. |\n| [UI](#ui) | [Shop pay button](#shop-pay-button) | Pure liquid dynamic Shop pay button for express checkout. |\n| [Schemas](#schemas) | [Schema website](#schema-website) | Renders the schema.org website JSON-LD for Site Name. |\n| [Schemas](#schemas) | [Schema organization](#schema-organization) | Renders the schema.org JSON-LD for Brand and Organization. |\n| [Schemas](#schemas) | [Schema article](#schema-article) | Renders the schema.org JSON-LD for a blog post or an article. |\n\n## Tools\n\nThese are tools that can be used to enhance the theme development experience.\n\n### Development screen indicator\n\nA simple indicator that shows which viewport size you are in. Useful for debugging and development.\n\nBuilt with [Tailwind CSS](https://tailwindcss.com) and can be added on the `theme.liquid` layout file.\n\nCopy code from [this file](./tools/development-screen-indicator.liquid).\n\n```liquid\n{% liquid\n  if settings.enable_development_mode\n    render 'development-screen-indicator'\n  endif\n%}\n```\n\nAn example of a setting to enable the development screen indicator on demand:\n\n```json\n{\n  \"type\": \"checkbox\",\n  \"id\": \"enable_development_mode\",\n  \"label\": \"Enable development mode\",\n  \"default\": false\n}\n```\n\n### Metaobject detector\n\nThis must be used inside a metaobject template. It detects the current metaobject and renders its properties or other metaobjects if it has any.\n\nCopy code from [this file](./tools/metaobject-detector.liquid).\n\n```liquid\n{% render 'metaobject-detector' %}\n```\n\nLearn more about metaobject templates [here](https://shopify.dev/docs/themes/architecture/templates/metaobject).\n\n## Meta\n\nThese are snippets that render meta tags to enhance the storefront with additional information.\n\n### Social share\n\nA small snippet to render all necessary meta tags for social sharing and page previews on socials.\n\nCopy code from [this file](./meta/social-share.liquid).\n\n```liquid\n{% render 'social-share' %}\n```\n\nYou can also check Shopify [recommandations](https://help.shopify.com/manual/online-store/images/showing-social-media-thumbnail-images) on social sharing.\n\n#### Debugging previews\n\nTo debug your social share previews, you can use the [Facebook Sharing Debugger](https://developers.facebook.com/tools/debug/) and the [Twitter Card Validator](https://cards-dev.twitter.com/validator).\n\n## Schemas\n\nThese JSON-LD snippets are based on the [Schema.org](https://schema.org) vocabulary and are used to improve the display of your pages on search engines.\n\n### Schema website\n\nRenders the schema.org website JSON-LD for Site Names.\n\nCopy code from [this file](./schemas/schema-website.liquid).\n\n```liquid\n{% render 'schema-website' %}\n```\n\n\u003e You can check the [Google Structured Data Docs](https://developers.google.com/search/docs/appearance/site-names) for more information.\n\n### Schema organization\n\nRenders the schema.org JSON-LD for Brand and Organization. Must be used on all templates.\n\nCopy code from [this file](./schemas/schema-organization.liquid).\n\n```liquid\n{% render 'schema-organization' %}\n```\n\n\u003e You can check the [Google Structured Data Docs](https://developers.google.com/search/docs/appearance/structured-data/logo) for more information about this schema.\n\n### Schema article\n\nRenders the schema.org JSON-LD for Blog post and article. Must be used on article cards or templates.\n\nCopy code from [this file](./schemas/schema-article.liquid).\n\n```liquid\n{% render 'schema-article' article: block.settings.article %}\n```\n\n\u003e You can check the [Google Structured Data Docs](https://developers.google.com/search/docs/appearance/structured-data/article) for more information about this schema.\n\n#### Debugging structured data\n\nTo debug your structured data, you can use the [Google Structured Data Testing Tool](https://search.google.com/structured-data/testing-tool) and the [Google Rich Results Test](https://search.google.com/test/rich-results).\n\n## UI\n\nThese are user interface snippets that are optimized and can be reused within your theme.\n\n### Image\n\nA powerful, less opinionated image snippet built on top of evergreen web technologies for Shopify storefronts.\n\nCopy code from [this file](./ui/image.liquid).\n\nCheck more informations about this image snippet as well as a preview of the snippet in action [here](https://github.com/odestry/theme-image).\n\n#### Arguments\n\nThe image has a very easy-to-understand sample API, and all of these arguments are optional:\n\n- `image`: The image object. This can be a product image or a media object of type image as well.\n- `class`: A string of classes, same as the class HTML attribute.\n- `lazyload`: By default, the snippet is eagerly loaded. If you want to lazyload the image, you can set this boolean parameter to true.\n- `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.\n- `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.\n- `placeholder`: The placeholder handle that is defined by Shopify. If you want to set other types of placeholders, check the Shopify documentation.\n\n#### Examples\n\nThere are many different ways to use this snippet. The easiest one is just by calling it with a render tag.\n\n##### Displaying a placeholder\n\nIf the image is blank or doesn't have any image object, it displays a placeholder like the following:\n\n```liquid\n{% render 'image' %}\n```\n\nYou can also pass a placeholder names handle to the snippet:\n\n```liquid\n{% render 'image', placeholder: 'product-apparel-4' %}\n```\n\n\u003e You can check a list of all the available placeholders illustrations [here](https://shopify.dev/docs/api/liquid/filters#placeholder_svg_tag).\n\n##### Displaying product featured image\n\nYou can easily display a product image with the following:\n\n```liquid\n{% render 'image' with product.featured_image %}\n```\n\nWhich is the same as:\n\n```liquid\n{% render 'image', image: product.featured_image %}\n```\n\nIt also accepts multiple arguments at once:\n\n```liquid\n{% render 'image' with product.featured_image,\n  alt: product.title,\n  class: 'aspect-square object-center',\n  lazyload: true,\n  placeholder: 'hero-apparel-3'\n%}\n```\n\n##### Lazyload images in a product grid\n\nYou 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.\n\n```liquid\n{% liquid\n  assign lazyload = false\n  for product in collection.products\n    if forloop.index \u003e 6\n      assign lazyload = true\n    endif\n\n    render 'image' with product.featured_image, lazyload: lazyload\n  endfor\n%}\n```\n\n##### Set aspect ratio of the image\n\nWe 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:\n\n```liquid\n{% render 'image' with product.featured_image, class: 'aspect-square' %}\n```\n\n**If you don't use tailwind, you can set this class on the image instead:**\n\n```css\n.image {\n  display: block;\n  vertical-align: middle;\n  aspect-ratio: auto;\n  height: auto;\n  object-fit: cover;\n  max-width: 100%;\n}\n```\n\nAnd then set this on the snippet class default value:\n\n```liquid\n  ...\n  assign class = 'image ' | append: class\n  ...\n```\n\n### Shop pay button\n\nPure liquid dynamic Shop pay button for express checkout.\n\nCopy code from [this file](./ui/shop-pay-button.liquid).\n\n```liquid\n{% render 'shop-pay-button' variant: variant: product.selected_or_first_available_variant %}\n```\n\nThis snippet is based on the [Shopify web component](https://shopify.dev/docs/custom-storefronts/additional-sdks/web-components#buy-with-shop-pay-component).\n\n## Contributing\n\nWe'd love your help! Please read our [contributing guide](https://github.com/odestry/.github/blob/main/CONTRIBUTING.md) to learn about our development process, how to propose bug fixes and improvements.\n\n## About\n\nOdestry 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](https://odestry.com).\n\n## License\n\nCopyright (c) 2024-present Odestry. See [LICENSE](/LICENSE.md) for further details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fodestry%2Ftheme-development-helpers","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fodestry%2Ftheme-development-helpers","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fodestry%2Ftheme-development-helpers/lists"}