Storeconnect Components

StoreConnect components and frontend interactivity

A {% component %} is a Liquid template the browser can ask the server to re-render on its own, in place, in response to a named DOM event. That is the platform's supported mechanism for updating part of a page. Everything else on this skill is how to drive it, how to wire JavaScript that survives it, and when to use a JSON page request instead.

Pick the approach first

Reach for a reload when the markup is server-owned. Reach for a client-side fetch when you need data and own the markup. A reload is a full storefront request: it re-runs controllers/theme and re-resolves the cart and customer, so it is the more expensive option.

The checkout caveat cuts both ways: the base theme renders its payment-information step as a component so that changing the total re-initializes the provider's JavaScript. Do not convert that step to a static render, and do not reimplement the payment request yourself.

Which reference to open

The tag

{% component "cart", reload: "sc.cart-updated" %}
{% component "checkout/shipping_rates/page", defer: true, reload: "sc.cart-updated" %}
{% component "orders/order_summary", source: order, reload: "sc.cart-updated" %}

• The template is components/<name>.liquid in the theme. Nested names work: "checkout/vouchers" → components/checkout/vouchers.liquid.
• reload: is a space-separated list of DOM event names. Any other option is passed to the template as a parameter.
• lazy: true renders nothing until a reload event fires. defer: true renders a placeholder and loads itself immediately, off the critical path.
• Inside the component, reloaded is true on a reload render, and context.<key> reads state persisted with {% context %}.

Dispatch a reload on document after the state change has succeeded:

document.dispatchEvent(new CustomEvent('sc.cart-updated'))

Non-negotiable rules

Never cache a component container. A cached container can render normally but fail to update when another visitor receives it. Keep the component outside the cached region. If the component contains an expensive, stable, read-only fragment, cache only that fragment inside the component template and include every output-changing input in items:. See references/component-reload.md.

Never cache a fragment containing a {% form %}. Keep every generated field, submitted value, validation message, and action control outside cached regions. This avoids broken submissions and visitor data appearing in the wrong response.

Never cache checkout, payment, cart, price, entitlement, account, or other customer-specific output. Separate stable public presentation from personalized and interactive markup, and cache only the stable public part. An omitted variation axis is a correctness and potential data-disclosure defect, not a performance nit.

An inline <script> inside a reloadable component never executes after a reload. The replacement HTML is inserted as a parsed fragment, and script elements created that way are inert — inline and src alike, so {% require %} inside a component also loads nothing on a reload. The symptom is behavior that works on first paint and is dead after the first update. Fix it by loading the JavaScript as a theme asset from the layout or page, re-initializing on DOM change, or delegating from an ancestor outside the component. See references/component-reload.md.

Never put anything sensitive in component parameters or {% context %}. Persisted context leaves your server, sits in the page, and comes back on the next reload. Store record identifiers and non-secret flags only; re-query and re-authorize server-side on every render, scoped by store and by the authenticated customer. Never place customer PII, payment values, prices you intend to trust, entitlement decisions, credentials, or tokens there. Do not construct, parse, log, or reuse the container's own attributes; use only the documented component behavior.

Escape for the context you are writing into. Liquid does not escape {{ }} output.

• HTML text and attributes: {{ value | escape }}.
• URLs: {{ value | url_encode }}.
• Data for JavaScript: render it as an escaped attribute and parse it, never as interpolated code.

<div data-example-state="{{ state | json | escape }}"></div>

const state = JSON.parse(el.dataset.exampleState)

Never interpolate a Liquid value into an inline <script> body: script content is raw text, so | escape corrupts it and an unescaped </script> in any string value breaks out of the block. Never eval a fetched response body.

Only reload what changed, and never on the happy path alone. Dispatch a reload event only after the mutation succeeded; handle the failure branch with a message, not a silent reload.

Fast failure triage

Full table with fixes: references/component-reload.md.

Performance

• One component covering a region beats several components listening to the same event: each is its own request, and each re-runs the theme controller.
• List every relevant event on one component's reload: rather than chaining event A to event B to reload a second component — chains serialize round trips.
• The reload payload is the component's whole rendered HTML. Keep components narrow; do not put a 50-row list in a component that exists to update one total.
• Debounce at the source for text input (200–300 ms) and show a loading state immediately, before the request.
• defer: true for slow or below-the-fold regions; lazy: true for content only revealed on demand.
• Cache only stable, read-only fragments inside the component template with {% cache %} and include every documented variation axis. Never cache the container, a form, payment content, or customer-specific output.

Verify after any change

1. Load the page: the component renders server-side on first paint (or shows its deferred placeholder).
2. Trigger the mutation: the region updates without a full page load and the browser console is clean.
3. Trigger it twice in quick succession: no duplicated handlers, no doubled actions.
4. Trigger the failure path: an error message appears and no stale content is shown as success.
5. Keyboard and screen reader: focus lands somewhere sensible and the change is announced.
6. Disable JavaScript: the underlying form or link still works as a full page request.
7. Repeat the interaction in a separate clean browser session and confirm no content or state is shared.
8. If you changed theme templates or assets, use the current supported publish and cache-refresh workflow — see storeconnect-sync-deploy.

Related skills

storeconnect-liquid for tags, filters, and Drops. storeconnect-forms for the form catalog and field drops feeding a component. storeconnect-controllers for server-side request logic — redirects, gating, capturing extra inputs — which is where logic belongs instead of a hand-built client mutation. storeconnect-theme-development for the base-theme override system and asset pipeline. storeconnect-debug-performance for {% cache %} key design and profiling a slow render.