# Family cards on a category page **Status:** current · **Verified:** 2026-10-25, source review against component and API contracts; neutral tutorial styling, not a live acceptance **Owner:** Vizen API documentation · **Serves:** `GET /docs/guide-family-cards` **Related:** `/docs/authentication`, `/docs/components`, `/docs/own-markup`, `/docs/catalogue`, `/docs/chrome`, `/docs/troubleshooting` ## 1. Result and prerequisites You will replace one category's stock grid with two insertions of one reusable component: family cards and a combo strip. A size or colour chip switches the whole SKU pane, including picture, stock, price and exact combo quote. Its link also works without JavaScript. Choose this path when the card design must be yours; keep the stock listing when its existing design is sufficient. Use the [key and permissions guide](/docs/authentication) before any API work. You need an existing category, product groups with size/colour axes, published members, and published combo sets. Configure **buyer List access for both the selected attributes and group axes first**: [catalogue §8.3](/docs/catalogue#8-3-who-sees-a-characteristic). That canonical section also explains the effect on filters; changing access just to obtain chips may expose a filter, so inspect the result. Check every field used below in `/docs/vz-keys.json` → `scope` before publishing. The example uses TOPLOFT codes `bed_size` and `bed_color`; substitute your own codes. The document and product ids below identify that example, not platform defaults. Resolve and verify your own ids. No production write is required to read or adapt this tutorial. Find the ids with the same key and contour: - `GET /product-groups` → `result[].id`, `members` and `axes[].attribute_id`. - `GET /attributes` → attribute `id` and `code`. The shop comes from the key; `company_id` is not a supported selector for this endpoint. - `GET /products?filter.category_id=&page.number=1&page.limit=48` → inspect `kind:"combo"` and select the **set product ids**. `filter.kind` is not supported; paginate if needed. The standard grid block has `payload.kind:"productListing"`. Replacing it removes its built-in filters, sorting, pagination UI and ItemList JSON-LD; see [components §4.7](/docs/components#4-7-put-it-on-one-product-or-one-category). An own-markup insertion is limited to **48 selected ids / items or groups**; use [own markup §2](/docs/own-markup#2-decide-first) for the feed contract. ## 2. Prepare the two component files Create `index.html` and `component.json` in the same component folder. Publish it as a **level-1 component** through [components §4.1](/docs/components). The complete HTML follows. CSS is inline, local to the `fc-` classes, and keeps neutral colours. The `tl-section` class belongs to the TOPLOFT theme; adapt it as described in §4. There is no custom script or client-side price calculation. `index.html`: ```html {{#show_catalog}}
{{/show_catalog}} {{#show_combos}}

{{ combo_heading }}

Все наборы ↗
{{/show_combos}} ``` `component.json`: ```json { "name": "Family cards and combo sets", "params": [ {"key": "show_catalog", "type": "bool", "label": "Показывать модели", "default": true}, {"key": "show_combos", "type": "bool", "label": "Показывать комбо", "default": false}, {"key": "catalog_label", "type": "text", "label": "Название области каталога", "default": "Товары", "max": 100}, {"key": "combo_heading", "type": "text", "label": "Заголовок комбо", "default": "Комбо-наборы", "max": 100}, {"key": "combo_all_url", "type": "link", "label": "Все наборы", "default": "/catalog/combo"} ] } ``` ## 3. Configure two insertions Follow the [canonical replacement workflow in components §4.8](/docs/components#4-8-replace-a-category-s-stock-grid-through-a-pat-with-rollback) for the API call sequence, snapshot, usage checks, validation, activation and rollback. The two JSON bodies below supply the insertion content for that workflow; do not bind them before its checks pass. Replace `component.ref` with your published document id. The same component is reused for both insertions. Family insertion, with an explicit order of representative products. `productsIds` contains **one member per family**: that member is the default selected SKU, and the id order is the family order ([catalogue §4.1](/docs/catalogue#4-1-selected-attributes-and-one-tile-per-product-group)). ```json { "item": { "name": "Category families", "sections": [{"type": "text", "payload": { "v": 2, "kind": "component", "props": { "blockWidth": "full", "paddingSides": {"top": 0, "right": 0, "bottom": 0, "left": 0}, "component": { "ref": 189, "params": {"show_catalog": true, "show_combos": false, "catalog_label": "Кровати"}, "productsMode": "collapse", "productsAttributes": ["bed_size", "bed_color"], "productsIds": [2503, 2509, 2498] } } }}] } } ``` Combo insertion, selecting **set ids** and explicitly disabling the catalogue: ```json { "item": { "name": "Category combo sets", "sections": [{"type": "text", "payload": { "v": 2, "kind": "component", "props": { "blockWidth": "full", "paddingSides": {"top": 0, "right": 0, "bottom": 0, "left": 0}, "component": { "ref": 189, "params": { "show_catalog": false, "show_combos": true, "combo_heading": "Комбо-наборы", "combo_all_url": "/catalog/combo" }, "productsIds": [2806, 2807] } } }}] } } ``` Omit `productsIds` and use `productsCategoryId` when you want the category feed rather than a selection. Feed boundaries, ordered selection, grouping and limits are canonical in [own markup §2](/docs/own-markup). `productsAttributes` belongs to each insertion: another category can reuse this component with its own attribute list. Change the template if it needs different explicit codes. A newly published member of an existing selected family is picked up without editing the HTML; a newly selected family or set requires changing its insertion selection. ## 4. Align with the theme Follow [chrome §3.7](/docs/chrome#3-7-reuse-the-active-theme-s-content-grid) to discover the active theme and its content-container class. Read `GET /themes/{id}/site` → `active_release_id` and `files[].path`, then `GET /themes/{id}/site/releases/{rid}/file?path=` → `text`. Use a path returned by that release, URL-encoded in the query; if there is no active release, there is no theme-folder CSS to reuse. In TOPLOFT that class is `tl-section`, used on both content roots above. In another theme, replace it with the discovered class. Keep the insertion wrapper settings from §3 and leave `contentWidth` unset. Let the theme own container width and gutters once; do not add a second root `max-width` or horizontal padding to compensate. Recheck image `sizes` against the resulting columns and actual rendered width ([image rules](/docs/own-markup#6-images)). Local CSS cannot resize the platform's outer wrapper. ## 5. Verify before acceptance Use the activation and read-back checks from components §4.8, then inspect the page as [troubleshooting §2](/docs/troubleshooting) describes: - Without JavaScript, the initial member is visible, other panes are hidden, and links open the correct member page. - Changing size preserves colour when the combination exists. A missing combination is disabled; a real out-of-stock member remains selectable. - Image, attribute text, price, stock, links and combo quote change together. The small dot describes `o.has_combo`, while the ribbon and quote use the selected member's `m.combo`; their contract is [own markup §2](/docs/own-markup). - Text chips and image chips identify the current selection. A modified click follows the link; a member with no rendered pane still opens its page. - The combo insertion shows only sets, their server prices and composition. Thumbnail requests match display size and DPR; no broken image source appears. - Both sections line up with the existing banner at desktop and mobile widths. A different category that should remain unchanged still looks unchanged. - Publishing another member of a selected family updates its available choices without an HTML edit. Repeating the workflow updates existing insertions rather than duplicating the grid. This example hides axes with fewer than two options and selects image-chip rendering from the first option's `image_url`. If your axis uses mixed image coverage, adapt that presentation to your data rather than assuming every option has a texture. Do not add client-side SKU substitution or quote maths. ## 6. Roll back and diagnose Restore the saved group and, if changed, the saved binding by the **rollback step of components §4.8**. Re-read and inspect the page. Component release rollback is separate: restoring group references does not restore a shared component's release. Retain the old blocks and snapshots during acceptance. If plain tiles appear, first check insertion mode and buyer access to axes; if a quote is absent, inspect the member's actual profitable combo rather than forcing a badge. Use [troubleshooting](/docs/troubleshooting) and the canonical field reference `/docs/vz-keys.json` for further diagnosis. Documentation links use heading fragments on the website: for example, `/docs/components#4-8-replace-a-category-s-stock-grid-through-a-pat-with-rollback`. For a raw API section use `GET /docs/components?section=4-8-replace-a-category-s-stock-grid-through-a-pat-with-rollback`. The dot in `4.8` becomes a hyphen (`4-8`, not `48`). A fragment navigates the rendered page; it does not select a section in an HTTP request to the API. ## 7. Silently ignored Unknown or invisible attribute codes do not produce attribute values; guard optional data with `vz-if`. The detailed feed and ignored-setting rules belong to [own markup §§2,8](/docs/own-markup), and component parameter rules to [components](/docs/components). A successful write alone does not prove that the intended feed or replacement is active: perform the read-back and browser checks above.