Розробникам · Теми

Довідник Liquid

Що бачить шаблон теми: глобальні обʼєкти, дані товару, каталогу, кошика й блогу, section і template, фільтри, теги й ліміти.

Контракт даних тем — версія 1, назви як у Shopify, snake_case. Зміни лише додають поля. Обʼєкт, якого немає на сторінці, — nil: перевіряйте {% if product %}. Ціни бувають двох видів: число в мінорних одиницях (копійки) — для фільтра money, і вже відформатований рядок — його виводять як є.

Глобальні обʼєкти

Доступні в кожній секції, сніпеті й {% render %}, на будь-якій сторінці.

Обʼєкт	Тип	Що
shop	обʼєкт	Магазин: назва, адреса, мова, валюта, контакти.
request	обʼєкт	Поточний запит: мова, шлях, вид сторінки, превʼю редактора.
routes	обʼєкт	Адреси головних сторінок мовою сторінки.
settings	обʼєкт	Глобальні налаштування теми з config/settings_schema.json.
linklists	обʼєкт	Меню магазину за handle: linklists.main, linklists['footer-store'].
collections	обʼєкт	Категорія за handle: collections['kava']; collections.all — увесь каталог.
metaobjects	обʼєкт	Записи типів контенту: metaobjects.<тип>.<handle>, metaobjects.<тип>.values.
blogs	обʼєкт	Свіжі статті: blogs.news — увесь блог, blogs.<код рубрики> — рубрика.
brands	обʼєкт	brands.all — бренди з опублікованими товарами.
customer	обʼєкт або nil	Покупець, що увійшов; nil для гостя.

shop, request, routes

Поле	Тип	Що
shop.name	рядок	Назва бренду з налаштувань, інакше назва сайту з SEO.
shop.url	рядок	Адреса вітрини.
shop.locale	рядок	Мова сторінки: uk, en …
shop.currency	рядок	Код основної валюти: UAH.
shop.phone, shop.email	рядок	Контакти з «Налаштувань»; порожній рядок, якщо не задано.
shop.address.summary, shop.working_hours	рядок	Адреса й графік роботи з «Налаштувань»; порожній рядок, якщо не задано. Тема не пише власних.
shop.metafields.custom.<ключ>	різне	Власні поля магазину (групи полів).
request.locale	рядок	Мова сторінки.
request.path	рядок	Шлях без домену й параметрів: /catalog/kava.
request.page_type	рядок	product, collection, search, blog, article, cart, metaobject або page (решта, також шапка й підвал).
request.design_mode	так/ні	true лише в превʼю редактора: підказки власнику показуйте тільки тоді.
routes.root_url	рядок	Головна.
routes.search_url	рядок	Пошук.
routes.cart_url	рядок	Кошик.
routes.collections_url, routes.all_products_collection_url	рядок	Каталог.

linklists — меню

linklists.<handle>: handle, title, levels (глибина) і links. Кожен пункт:

Поле	Тип	Що
title	рядок	Назва пункту мовою сторінки.
url	рядок	Шлях у магазині (/catalog/kava) або повна адреса іншого сайту.
active	так/ні	Шлях пункту збігається зі сторінкою.
current	так/ні	Збігаються ще й параметри запиту.
child_active, child_current	так/ні	Те саме для будь-якого вкладеного пункту.
levels	число	Скільки рівнів під пунктом.
links	список	Вкладені пункти тієї самої форми.
key	рядок або nil	Стабільний id пункту; не змінюється при перейменуванні. nil у вбудованому меню, яке власник ще не зберіг.
image	рядок або nil	Картинка пункту.
badge	обʼєкт або nil	{title, tone}; tone — accent, sale або muted.
icon_svg	рядок або nil	Іконка з бібліотеки ядра готовим <svg class="sf-menu-icon"> у кольорі тексту.
icon_url	рядок або nil	Власна SVG-іконка як data:-адреса — для <img> або CSS-маски.

collections, blogs, brands, metaobjects

Поле	Тип	Що
collections['handle'].title, .handle, .url	рядок	Категорія за кодом з адреси.
collections['handle'].image	рядок або nil	Картинка категорії.
collections['handle'].products	список карток	До 12 товарів категорії (картка — нижче).
collections['handle'].products_count	число	Опубліковані товари разом з підкатегоріями.
collections['handle'].metafields.custom.<ключ>	різне	Власні поля категорії.
collections.all	обʼєкт	Увесь каталог: title, handle = all, url, products — 12 найновіших, products_count. Категорія з кодом all має перевагу.
blogs.news.title, .url	рядок	Блог.
blogs.news.articles	список статей	До 12 найновіших; blogs.<код рубрики> — статті рубрики, невідомий код — nil.
brands.all	список	До 24 брендів: title, url, logo.
metaobjects.<тип>.<handle>	запис або nil	Опублікований запис: handle, title, url і поля за ключами.
metaobjects.<тип>.values	список записів	До 50 опублікованих, у порядку типу.

Поля запису: текст, число, дата, колір і посилання — як є; фото й файл — URL; список фото — масив URL; посилання на товар, категорію, сторінку чи запис — ідентифікатори; повторювач — масив рядків з тими самими правилами.

Картка товару в списках

Однакова у всіх списках: collections[…].products, collections.all.products, collection.products, search.results, product.related_products і налаштування product та product_list.

Поле	Тип	Що
id	число	Id товару — для {% component 'product.card', product: p.id %}.
handle	рядок	Код з адреси.
title	рядок	Назва.
url	рядок	Шлях до товару.
available	так/ні	Є в наявності.
price	число	Найменша ціна в копійках: {{ p.price \| money }}.
compare_at_price	число або nil	Стара ціна, лише коли вона більша за ціну.
featured_image	фото або nil	Перше фото.
images	список фото	Усі фото.
variant_id	число або nil	Варіант, який купує {% component 'commerce.add-to-cart', variant: p.variant_id %}.

Сніпет отримує іншу картку — з готовими цінами, знижкою, бейджами й кольорами: див. Сторінки теми.

Фото

Поле	Тип	Що
src	рядок	Оригінал.
alt	рядок	Опис фото; у фото товару — назва товару.
width, height	число або nil	Розмір оригіналу.
srcset	рядок	Готові розміри WebP 320–1920 px для srcset.
srcset_avif	рядок	Те саме в AVIF.
object_position	рядок	Точка фокусу з редактора фото; 50% 50% без неї. Для рамки з object-fit: cover.

Налаштування image_picker секції — лише URL, не обʼєкт фото. Фото в картці сніпета product-card мають src, srcset, width, height і alt.

product — сторінка товару

На сторінці товару (request.page_type = product) і в сніпеті product-page.

Поле	Тип	Що
id, title, url	число, рядок	Товар.
description	рядок HTML	Опис; без нього — короткий опис.
short_description	рядок	Короткий опис.
available	так/ні	Є в наявності.
price	число	Ціна в копійках.
currency	рядок	Код валюти.
images, featured_image	список фото, фото	Фото товару.
variants	список	{id, title, available, price} — price у копійках.
selected_or_first_available_variant	варіант або nil	Вибраний, інакше перший у наявності, інакше перший; з полем attributes.
tags	список рядків	Мітки товару.
attributes.<код>	обʼєкт	Характеристика: name, type, unit, group (розділ таблиці), variant_axis, values [{name, slug, color, url}]; url веде в каталог з цим фільтром, якщо він є. Ключ — код характеристики або attribute_<id>.
related_products	список карток	До 8: «З цим купують», потім новинки основної категорії.
vendor	рядок	Назва бренду або порожньо.
brand	обʼєкт або nil	{title, url, logo}.
metafields.<простір>.<ключ>	різне	Поля, видимі на вітрині: характеристики із застосунків, метаполя, metafields.custom — власні поля товару.
breadcrumbs	список	Лише в product-page: категорії над товаром [{name, url}].

collection, search, blog, article, page

Поле	Тип	Що
collection.title, .url	рядок	Каталог, категорія, бренд або SEO-сторінка фільтра.
collection.kind	рядок	catalog, category або brand.
collection.products	список карток	Товари поточної сторінки з урахуванням фільтрів.
collection.products_count	число	Скільки знайдено.
collection.paginate	обʼєкт або nil	{current_page, pages, items}.
collection.metafields.custom	обʼєкт	Власні поля категорії.
search.terms	рядок	Запит.
search.results, .results_count, .paginate	список, число, обʼєкт	Знайдені товари.
blog.articles, .paginate	список, обʼєкт	Статті сторінки блогу.
blog.tag	рядок	Відкритий тег або порожньо.
blog.category, blog.author	обʼєкт або nil	На сторінці рубрики чи автора.
article.id, .title, .excerpt, .url	різне	Стаття.
article.published_at	рядок	Дата ISO 8601: {{ article.published_at \| date: '%d.%m.%Y' }}.
article.tags, .image	список, фото	Теги й обкладинка.
article.category	обʼєкт або nil	{title, handle, url, description}.
article.author	обʼєкт або nil	{name, handle, url, position, bio, image, links}.
article.metafields.custom	обʼєкт	Власні поля статті.
page.id, .title, .handle, .url	різне	Сторінка магазину; у вкладеної url — повний шлях.
page.metafields.custom	обʼєкт	Власні поля сторінки.
entry, content_type	обʼєкт	Сторінка запису (page_type = metaobject): запис як у metaobjects і тип {handle, name, name_plural, url}.

Пагінація — обʼєкт paginate з current_page, pages і items. Тегу {% paginate %} немає: перемикач сторінок і фільтри малює компонент catalog.results, а в пошуку — search.results.

cart, checkout, order, customer

Поле	Тип	Що
cart.items	список	{title, variant, quantity, price, line_price, image}; price і line_price — готові рядки, image — URL мініатюри.
cart.item_count	число	Скільки одиниць у кошику.
cart.upsell_count	число	Скільки товарів «З цим купують»; заголовок над cart.upsell показуйте, коли більше 0.
checkout.item_count	число	У сніпеті checkout.
checkout.subtotal, .total	рядок	Готові суми.
checkout.currency	рядок	Код валюти.
checkout.mode	рядок	new — новий покупець, registered — зареєстрований.
order.reference, .status	рядок	У сніпеті order-page.
order.subtotal, .total, .currency	рядок	Суми замовлення.
order.lines	список	{title, variant_title, quantity, line_price}.
order.shipping_method	рядок	Спосіб доставки.
customer.id, .first_name	число, рядок	Покупець, що увійшов.
customer.metafields	обʼєкт	Метаполя покупця, видимі на вітрині.

section, block, template

Поле	Тип	Що
section.id	рядок	Id секції на сторінці — для унікальних id в розмітці.
section.settings.<id>	різне	Значення налаштувань поверх default схеми.
section.blocks	список	Блоки в порядку, який задав власник.
block.id, block.type	рядок	type — тип зі схеми або @app для блоку додатка.
block.settings.<id>	різне	Налаштування блоку.
block.attributes	рядок	<div {{ block.attributes }}> дає вибір блоку кліком у превʼю; на вітрині порожньо.
template.name	рядок	Вид сторінки: product, collection, cart, blog …
template.suffix	рядок або nil	Назва шаблону: gift для product.gift; nil для default.
template.settings.<id>	різне	Налаштування зі {% schema %} сніпета сторінки.

Тип налаштування	Що отримує Liquid
text, textarea	Текст мовою сторінки.
richtext	HTML.
checkbox	true або false.
number, range	Число.
select, radio	value вибраного варіанта.
color, url	Рядок.
image_picker	URL фото або nil.
link_list	Меню як у linklists або nil.
collection	Категорія як collections['handle'] або nil.
collection_list	До 12 категорій.
product	Картка товару або nil.
product_list	До 12 карток.
metaobject, metaobject_list	Запис або до 50 записів.

Видалене й неопубліковане випадає. У глобальних налаштуваннях теми (settings) посилання на каталог лишаються ідентифікаторами.

Фільтри

Фільтр	Що робить
money	Копійки → ціна з валютою у валюті, яку обрав покупець: {{ p.price \| money }}.
money_without_currency	Те саме без знака валюти.
image_url	Фото або URL → адреса; з width: 600 — найменший WebP від 600 px; height рахує ширину за пропорцією.
image_tag	Фото → <picture> з AVIF і WebP; параметри sizes, alt, class, loading, width. URL або фото без розмірів — звичайний <img>.
asset_url	Файл з assets/ → його адреса; порожньо, якщо файлу немає.
t	Ключ → слово мовою сторінки (докладно — /docs/theme-translations).
json	Значення → JSON, безпечний усередині <script>.
script_tag, stylesheet_tag	Лише в магазині з дозволеним JavaScript; в інших нічого не виводять.

Стандартні фільтри Liquid: abs, append, at_least, at_most, capitalize, ceil, compact, concat, date, default, divided_by, downcase, escape, escape_once, find, find_index, first, floor, has, join, last, lstrip, map, minus, modulo, newline_to_br, plus, prepend, reject, remove, remove_first, remove_last, replace, replace_first, replace_last, reverse, round, rstrip, size, slice, sort, sort_natural, split, squish, strip, strip_html, strip_newlines, sum, times, truncate, truncatewords, uniq, upcase, url_decode, url_encode, where. Невідомий фільтр — помилка рендеру.

Тег	Що
{% component 'тип', параметр: значення %}	Ставить компонент ядра; лише дозволені в цьому місці (/docs/theme-components).
{% render 'сніпет', змінна: значення %}	Сніпет теми; глобальні обʼєкти видно в ньому, section і block — ні. {% include %} немає.
{% render_block block %}	Блок додатка (@app) у секції.
{% schema %}…{% endschema %}	Схема секції; у сніпеті сторінки — налаштування template.settings.
{% stylesheet %}…{% endstylesheet %}	CSS один раз на сторінку, скільки б копій секції не стояло.
{% javascript %}…{% endjavascript %}	JavaScript один раз на сторінку; лише в магазині з дозволеним JavaScript.
assign, capture, if, unless, case, for, cycle, tablerow, increment, decrement, liquid, echo, raw, comment	Стандартні теги Liquid.

Ліміти рендеру

Що	Ліміт
Пошук категорій collections['…']	20 на рендер, далі nil.
Рубрики blogs.<код>	5 на рендер.
Типи metaobjects	20 на рендер; до 50 записів у values.
Товари в одному списку	12; related_products — 8.
Вивід одного рендеру	200 000 символів (у магазині з дозволеним JavaScript — 800 000); секція в шапці чи підвалі — до 150 КБ власної розмітки, компоненти ядра не рахуються.
Присвоєння	Мають ліміт за розміром значення: присвоюйте номер (forloop.index0), а не цілий товар.