# Theme setup

The pack selector block, and how it adapts to any theme.

Canonical: https://cartrella.com/docs/bundles/theme-setup

The **Cartrella pack selector** is one theme app block with two behaviors,
decided automatically by the page it's on:

- On a product that's the **base of fixed packs** → a size ladder:
  *Single · Pack of 2 · Pack of 4* with one buy button at the selected price.
- On a **mix container** product → the build-your-pack grid.
- On any other product → it stays hidden.

## Add the block

Online Store → **Customize** → open a product page → **Add block → Apps →
Cartrella pack selector** (place it between the price and the buy button) →
**Save**.

## Fitting your theme

The block inherits your theme's fonts, and its button adapts in three tiers:

1. **Match theme button** (default) — the pack button adopts your theme's own
   add-to-cart button styling automatically. On most themes this needs zero
   configuration.
   - Custom-built product pages: point it at your button with **Button to
     match (CSS selector)**, e.g. `.dark-button.main-button`.
2. **Style settings** — button text, highlight badge ("Best value" — empty
   hides it), show/hide savings and per-item price, accent color, corner
   radius, or full **Custom colors**.
3. **Custom CSS** — a block setting for theme developers. Stable hooks:
   `.cartrella-pack`, `.cartrella-pack__sizes`, `.cartrella-size`,
   `.cartrella-size__badge`, `.cartrella-size__price`, `.cartrella-size__sub`,
   `.cartrella-pack__grid`, `.cartrella-pack__item`, `.cartrella-pack__stepper`,
   `.cartrella-pack__count`, `.cartrella-pack__add`.

Prices are never editable in the block — they come from your published packs,
so the display can't drift from what checkout charges.

## Fully custom storefronts (headless)

If your theme renders its own pack UI, skip the block entirely. Fetch the
published configuration from the app proxy on your own domain:

```
GET /apps/cartrella/bundles?product_id=<numeric product id>
```

- On a fixed-pack base product it returns the size ladder (pack variant ids
  to add to the cart).
- On a mix container it returns the size, per-item price, and eligible
  products; add the container variant with the line property
  `_cartrella_pack` = `"gid:qty,gid:qty"`.

Your UI, Cartrella's pricing authority — checkout still re-validates
everything.

> **Proxy path:** if another app already used the `/apps/cartrella` path when
> you installed, Shopify assigns a suffix (e.g. `/apps/cartrella-1`). Set it
> in the block's **App proxy path** setting.