> ## Documentation Index
> Fetch the complete documentation index at: https://developers.papelship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Довідник app blocks

> Усі блоки платформи: аргументи, псевдоніми, що вони рендерять, поведінка спливного вікна, бічної панелі чи навігації та які типи тем їх підтримують.

AI-агенти отримують той самий довідник через MCP тем: інструмент `get_reference` (тема `app_blocks`) і ресурс `papelship://reference/app-blocks`. Редактор коду, `validate` і `save_draft` попереджають про невідомі блоки, невідомі або неправильно типізовані аргументи та блоки, які даний тип теми не підтримує.

Блоки платформи (`{% app_block %}` / data-app-block): аргументи, поведінка, підтримка для кожного типу; заблоковані блоки сторінок.

```liquid theme={"system"}
{% app_block 'buy_now', product_id: product.id, mode: 'embed' %}
```

```html theme={"system"}
<div data-app-block="buy_now" data-props='{"product_id":"PRODUCT_ID","mode":"embed"}'></div>
```

| Блок | Поведінка | liquid | design | code | twin |
| - | - | - | - | - | - |
| `add_to_cart` | бічна панель | так | так | так\* | так\* |
| `buy_now` | навігація | так | так | так | так |
| `cart_count` | бічна панель | так | так | так\* | так\* |
| `cart_drawer` | бічна панель | так | так | так\* | так\* |
| `checkout_button` | навігація | так | так | так | так |
| `currency_selector` | вбудований | так | так | так\* | так\* |
| `language_selector` | навігація | так | так | так | так |
| `newsletter_form` | форма | так | так | так | так |
| `powered_by` | вбудований | так | ні | ні | ні |
| `quick_view` | діалог | так | так | так | так |
| `recently_viewed` | вбудований | так | так | так\* | так\* |
| `reviews_widget` | вбудований | так | так | ні | ні |
| `variant_picker` | вбудований | так | так | так | так |
| `wishlist_button` | вбудований | так | так | так | так |

`так*`: працює, з приміткою нижче. У кодових секціях і виокремлених двійниках блоки кошика використовують бічну панель кошика платформи, а не власну панель React-теми; значок кошика теми залишається синхронізованим.

## add\_to\_cart

Кнопка додавання в кошик для одного товару. Додає товар у спільний кошик вітрини та відкриває бічну панель кошика. Якщо товар має кілька варіантів і варіант не обрано: запитує variant\_picker поруч, інакше відкривається сторінка товару.

| Аргумент | Тип | Обов'язковий | Псевдоніми | За замовчуванням | Опис |
| - | - | - | - | - | - |
| `product_id` | product | так | `product` | | ID або хеш-ID товару (product.id / product.hash\_id). Також приймається об'єкт товару. |
| `variant_id` | id | | `variant` | | ID варіанта; за замовчуванням: варіант, обраний у variant\_picker поруч, інакше варіант за замовчуванням. |
| `quantity` | integer | | | `1` | Кількість (1 або більше). |
| `label` | string | | | | Текст кнопки (за замовчуванням "Add to cart", із перекладом). Ігнорується, якщо заповнювач має власну розмітку. |
| `mode` | enum (`page`, `embed`) | | | | Не діє: add\_to\_cart завжди додає в кошик. Для оформлення використовуйте buy\_now. |

## buy\_now

Кнопка швидкої купівлі для одного товару. `mode: 'page'` (за замовчуванням) переходить до оформлення платформи лише з цим товаром (кошик зберігається). `mode: 'embed'` відкриває спливне вікно оформлення поверх сторінки (iframe платформи; дані картки ніколи не потрапляють до теми) і переходить на сторінку, якщо віджет не вдається завантажити.

| Аргумент | Тип | Обов'язковий | Псевдоніми | За замовчуванням | Опис |
| - | - | - | - | - | - |
| `product_id` | product | так | `product` | | ID або хеш-ID товару. Також приймається об'єкт товару. |
| `variant_id` | id | | `variant` | | ID варіанта; за замовчуванням: варіант, обраний у variant\_picker поруч. |
| `quantity` | integer | | | `1` | Кількість (1 або більше). |
| `label` | string | | | | Текст кнопки (за замовчуванням "Buy now", із перекладом). |
| `mode` | enum (`page`, `embed`) | | | `page` | `page` = сторінка оформлення; `embed` = спливне вікно оформлення поверх поточної сторінки. |

## cart\_count

Кнопка кошика з кількістю товарів ("Cart `<n>`"); ваша власна розмітка зберігає свій вигляд, а дочірній елемент `[data-ps-count]` отримує число. Натискання відкриває бічну панель кошика. Без аргументів.

## cart\_drawer

Налаштовує висувну бічну панель кошика (позиції, кількості, знижки акцій, шкала безкоштовної доставки, додаткові пропозиції, оформлення). Нічого не рендерить на своєму місці; параметри задає перший `cart_drawer` на сторінці.

| Аргумент | Тип | За замовчуванням | Опис |
| - | - | - | - |
| `upsell` | string | | Handle або ID колекції, товари якої пропонуються в панелі. |
| `upsell_limit` | integer | `3` | Кількість додаткових товарів для показу (1-6). |
| `upsell_heading` | string | | Заголовок додаткових пропозицій (за замовчуванням "You may also like"). |
| `free_shipping` | boolean | `true` | `false` приховує шкалу прогресу безкоштовної доставки. |

## checkout\_button

Кнопка оформлення замовлення для всього кошика (неактивна, поки кошик порожній). `mode: 'page'` (за замовчуванням) переходить на `<store>/checkout`; `mode: 'embed'` відкриває спливне вікно оформлення; після оплати кошик очищається.

| Аргумент | Тип | За замовчуванням | Опис |
| - | - | - | - |
| `label` | string | | Текст кнопки (за замовчуванням "Checkout", із перекладом). |
| `mode` | enum (`page`, `embed`) | `page` | Сторінка оформлення або спливне вікно. |

## currency\_selector

Вибір валюти відображення (прихований, якщо валют менше двох). Зберігає валюту відображення (оформлення завжди списує кошти у валюті магазину) і генерує `papelship:currency-change`. У кодових секціях і двійниках передавайте `currencies`: ці сторінки знають лише валюту магазину.

| Аргумент | Тип | Опис |
| - | - | - |
| `label` | string | Текст підпису. |
| `currencies` | list | Коди валют (`"USD,EUR,TRY"` або масив); за замовчуванням: валюти відображення магазину. |

## language\_selector

Вибір мови магазину (прихований, якщо магазин має одну мову). Встановлює cookie мови та перезавантажує сторінку. Аргумент: `label`.

## newsletter\_form

Форма підписки на розсилку з явним прапорцем згоди. Надсилає дані на ендпоінт лідів платформи; у попередньому перегляді підписка не відбувається. Аргументи: `label`, `placeholder`, `button`, `consent_text`.

## powered\_by

Позначка "Powered by PapelShip" (прихована на тарифах, які дозволяють її приховати). Лише для тем Liquid: сторінки дизайнів і футери React-тем отримують цю позначку від платформи автоматично.

## quick\_view

Кнопка швидкого перегляду для одного товару: відкриває діалог із зображеннями, ціною, варіантами та кнопкою додавання в кошик. Аргументи: `product_id` (обов'язковий, псевдонім `product`), `label`.

## recently\_viewed

Нещодавно переглянуті відвідувачем товари (у цьому браузері); нічого не рендерить, якщо список порожній. Товари записуються на сторінках товарів Liquid (сторінки товарів React-тем перегляди не записують). Аргументи: `limit` (за замовчуванням 4, 1-20), `heading`.

## reviews\_widget

Опубліковані відгуки: про товар сторінки на сторінках товарів, інакше про магазин. Не підтримується в кодових секціях і двійниках (ці сторінки не містять даних відгуків; використовуйте секцію відгуків React-теми). Аргументи: `heading`, `limit` (за замовчуванням 5, 1-50), `write` (за замовчуванням `true`; `false` приховує посилання для написання відгуку).

## variant\_picker

Вибір варіанта (групи перемикачів) для одного товару. `add_to_cart` / `buy_now` того самого товару в найближчому спільному контейнері (або елементі `data-ps-scope`) використовують обраний варіант; тексти `data-ps` price / compare-price / stock змінюються відповідно. Аргумент: `product_id` (обов'язковий, псевдонім `product`).

## wishlist\_button

Перемикач обраного для одного товару (кнопка-сердечко з `aria-pressed`). Зберігається в браузері та синхронізується з обліковим записом клієнта після входу. Аргумент: `product_id` (числовий ID; хеш-ID не зберігаються в обліковому записі).

## Заблоковані блоки сторінок

| Блок | Сторінка | Файл теми Liquid | Файл дизайну |
| - | - | - | - |
| `checkout_form` | Сторінка оформлення замовлення | `templates/checkout.liquid` | `pages/checkout.liquid` або `.html` |
| `cart_view` | Сторінка кошика | `templates/cart.liquid` | `pages/cart.liquid` або `.html` |
| `customer_login` | Сторінка входу | `templates/customers/login.liquid` | `pages/login.liquid` або `.html` |
| `customer_account` | Сторінка облікового запису | `templates/customers/account.liquid` | `pages/account.liquid` або `.html` |
| `order_track` | Сторінка відстеження замовлень | `templates/customers/track.liquid` | `pages/track.liquid` або `.html` |

Кожен блок працює лише один раз, у своєму файлі перевизначення. Пакети коду React-тем не мають перевизначень сторінок.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.