Waarom Horizon geen main-cart-items.liquid heeft (en hoe je de cart-items-component aanpast)

Horizon beschikt niet over een main-cart-items.liquid sectiebestand. Dat bestand bestaat in Dawn, niet in Horizon. In Horizon wordt de weergave van winkelwagen-items afgehandeld door main-cart.liquid (de sectie) samen met het aangepaste webElement cart-items-component, en het aanpassen van de winkelwagen betekent werken binnen die webcomponent-architectuur in plaats van een vlak Liquid-sectiebestand te bewerken.

Belangrijkste punten

• Horizon verving het monolithische main-cart-items.liquid-patroon met een zelfstandige cart-items-component webcomponent.
• Het rechtstreeks bewerken van kernbestanden van Horizon wordt overschreven bij de volgende thema-update (Horizon brengt wekelijkse releases uit).
• Winkelwagen-attributen gaan in main-cart-footer.liquid; regelitem-eigenschappen worden weergegeven via cart.items iteratie in main-cart.liquid.
• Het veilige aanpassingspad is: nieuwe blokbestanden in blocks/, voorgevoegde sectiebestanden en een GitHub upstream-tak om Shopifys updates schoon te integreren.
• Apps gebouwd voor de oudere Online Store 2.0-architectuur breken vaak op Horizons winkelwagen omdat webcomponenten binnenin Shadow DOM draaien.

Waarom het bestand dat je zoekt niet bestaat

Shopifys helpbestanden en talrijke tutorials verwijzen naar main-cart-items.liquid omdat Dawn zijn winkelwagen zo structureert. Dawn splitst de winkelwagenpagina in twee secties: main-cart-items.liquid (de regelitemtabel) en main-cart-footer.liquid (totalen, afrekenen-knop, attributen). Horizon repliceert deze splitsing niet.

Horizon is de vlaggenschip van een nieuwe generatie Shopify-thema's gebouwd op het Horizon-framework. Het architectuurprincipe is: elk zinvol interactief onderdeel van de pagina is een zelfstandige webcomponent. De winkelwagenladen, de variantkiezer, de voorspellende zoekopdracht, geen ervan zijn monolithische Liquid-secties zoals Dawn ze implementeert. In plaats daarvan zijn het ingekapselde aangepaste elementen die samengesteld zijn in een enkel main-cart.liquid sectiebestand.

Dit veroorzaakte onmiddellijke verwarring toen Horizon lanceerde op Summer Editions 2025. In februari 2026 waren de Shopify Community-forums vol met handelaren op Horizon 3.3.0 die hun sections/ directory doorzoeken naar main-cart-items.liquid en niets vinden, omdat het daar nooit was.

Hoe de Horizon winkelwagen-architectuur er werkelijk uitziet

In plaats van een apart sectiebestand per winkelwagen-zone is Horizons winkelwagenpagina gestructureerd rond main-cart.liquid als de buitenste sectie, met het aangepaste <cart-items-component> element dat de interactieve regelitem-weergave erin afhandelt.

De belangrijkste architectuurbeslissingen, rechtstreeks uit de officiële Horizon GitHub-repo:

• Eerst server-weergegeven. HTML wordt weergegeven door Shopifys servers via Liquid. Bedrijfslogica zoals geldformattering en vertalingen blijft op de server, niet op de client.
• Web-native progressieve verbetering. Het thema richt zich op moderne browsers zonder polyfills, en asynchrone herweergave van winkelwagenstatus (hoeveelheid-updates, verwijderingen) wordt spaarzaam afgehandeld als progressieve verbetering bovenop de server-weergegeven HTML.
• Gescoped JavaScript. Horizon bevat een specifieke JS-klasse die prestaties meet voor componenten zoals het productformulier, winkelwagenladen en winkelwagen-korting, wat JS-gewicht per component minimaal houdt.

De cart-items-component is het aangepaste element (<cart-items-component>) dat de regelitemtabel omwikkelt. Het luistert naar winkelwagewijzigingsgebeurtenissen (toevoegen, verwijderen, hoeveelheid bijwerken) en geeft zijn binnenste HTML opnieuw weer via de Cart Ajax API zonder volledige pagina-herlaad. Het Liquid-sjabloon bevindt zich in main-cart.liquid, niet in een apart bestand.

Winkelwagen-attributen (aangepaste velden op orderniveau zoals een geschenkaantekening of een datumkiezer) worden vastgelegd via main-cart-footer.liquid. Volgens Shopifys documentatie voor winkelwagen-sjablonen voeg je een <input> toe met name="attributes[your-field-name]" en form="cart" in dat voettekstbestand. Dat attribuut is dan toegankelijk via {{ cart.attributes['your-field-name'] }}.

Regelitem-eigenschappen (per-productgegevens) worden niet automatisch weergegeven door cart-items-component. Je moet cart.items doorlopen in main-cart.liquid en de .properties hash van elk item uitvoeren. Shopifys eigen documentatie stelt dat als twee dezelfde items met unieke regelitem-eigenschappen worden toegevoegd, ze in aparte regelitems worden gesplitst, een gedrag dat in je sjabloonlogica rekening mee moet houden.

Hoe je de winkelwagen veilig op Horizon aanpast

Horizon brengt wekelijkse thema-updates uit. Als je kernbestanden rechtstreeks bewerkt, worden die bewerkingen overschreven de volgende keer dat je een update toepast. De GitHub-repo heeft zelfs een live versiediscrepantie opgemerkt: vanaf april 2026 was de Theme Store op v3.5.1 terwijl de GitHub-repo op v3.4.0 was gepind, wat betekent dat enkele wijzigingen eerst in de store terechtkwamen. Dit benadrukt de noodzaak van een goede Git-workflow.

De drie-tak GitHub-instelling

Shopifys officiële Growth Services-gids (gepubliceerd november 2025) beveelt aan om alle Horizon-aanpassingen te beheren via een gedisciplineerde vertakkingsstrategie:

1. upstream/horizon, volgt de officiële Shopify/horizon repository rechtstreeks. Je haalt updates hier eerst op.
2. main, je aangepaste, productiegerede tak. Je voegt upstream in main in na het beoordelen van diffs.
3. Functietakken, alle nieuwe winkelwagen-aanpassingen worden hier gebouwd en in PR'd naar main.

Voor het instellen van de upstream navigeer je naar je lokale themamap en voer je uit:

git remote add upstream https://github.com/Shopify/horizon.git
git fetch upstream

Wanneer Shopify een nieuwe Horizon-versie uitbrengt, haal je deze op in je upstream-tak, los je conflicten op je aangepaste bestanden op en voeg je samen. Dit houdt je winkelwagen-aanpassingen intact bij elke wekelijkse update.

Waar je winkelwagen-aanpassingen eigenlijk moet plaatsen

Weersta de verleiding om de volledige main-cart.liquid in een custom. voorgevoegde versie te kopieren tenzij je dit absoluut moet doen. Een volledige kopie betekent dat je handmatig elke toekomstige Shopify-update op die sectie moet differentiëren en opnieuw toepassen. In plaats daarvan voeg je alleen toe wat je nodig hebt in nieuwe blokbestanden waar mogelijk, en houdt de core-sectie ongewijzigd.

Interactieve winkelwagen-extensies als webcomponenten bouwen

Horizons performance-filosofie is expliciet: geen externe carousel of UI-bibliotheken. Als je interactief gedrag in de winkelwagen nodig hebt (een geanimeerde hoeveheid-stepper, een real-time gratis verzendingsvorderingsbalk), bouw het als een vanilla Web Component die alleen initialiseert wanneer zichtbaar. Gebruik IntersectionObserver om initialisatie uit te stellen voor alles wat niet onmiddellijk in beeld is, en schrijf je stijlen in {% style %} tags om ze gescoped en vrij van extra HTTP-verzoeken te houden.

class CartUpsellBadge extends HTMLElement {
  connectedCallback() {
    // Alleen initialiseren wanneer winkelwagen open is / element zichtbaar is
    this._observer = new IntersectionObserver((entries) => {
      if (entries[0].isIntersecting) {
        this._init();
        this._observer.disconnect();
      }
    });
    this._observer.observe(this);
  }

  _init() {
    // Upsell-gegevens ophalen, weergeven in this.innerHTML
  }
}
customElements.define('cart-upsell-badge', CartUpsellBadge);

Laad dit script via <script type="module"> zodat de browser het efficiënt afhandelt, passend bij Horizons eigen scriptlaadinpatroon.

Het Shadow DOM app-compatibiliteitsprobleem

Dit is de gotcha die de meeste handelaren mid-project betrapt. Apps gebouwd voor Dawns oudere Online Store 2.0-architectuur haken vaak in de winkelwagen door de DOM naar een hoeveelheids-invoer of een winkelwagentotaal span te vragen en naar wijzigingsgebeurtenissen te luisteren. Dat patroon werkt niet op Horizon.

Omdat Horizons winkelwagen-componenten webcomponenten zijn, blokkeren apps die Shadow DOM-inkapseling gebruiken het oude document.querySelector('.cart-item__quantity') patroon. De internals van het aangepaste element zijn niet toegankelijk van buiten de shadowwortel via standaard DOM-queries.

Controleer voor het installeren van een winkelwagen-app op Horizon de app-listing expliciet op een opmerking "Horizon support". Apps die een "Built for Shopify" badge hebben ontvangen, zijn performance-getest, maar badgestatus alleen garandeert geen Shadow DOM-compatibiliteit. Wanneer twijfelachtig, installeer op een dubbel thema en test hoeveelheidsupdates, verwijderingen en de afrekenbetaalketen end-to-end voordat je live gaat.

De huidige GitHub-achterstand en wat dit voor jou betekent

Vanaf medio 2026 heeft de Shopify/horizon GitHub-repo periodes gehad waarin deze achterliep bij de versie live in de Theme Store. In april 2026 merkten communitydevelaars op dat de repo op v3.4.0 was terwijl de Theme Store v3.5.1 serveerde. Shopify bevestigde dat de hoofdtak code voor functies kan bevatten die nog niet zijn uitgebracht, wat betekent dat het gepubliceerde thema en de repo in beide richtingen uit synch kunnen zijn.

Praktische implicatie: behandel de GitHub-repo niet als de canonieke bron van de versie in je winkel. Haal het nieuwste thema op uit je Shopify-beheerder (Online Store > Thema's > Thema-bestand downloaden) en maak een diff tegen de GitHub-repo voordat je aannames doet over welke code live is. Gebruik Theme Check (gebundeld in Shopify CLI en beschikbaar als VS Code-extensie die Horizon automatisch aanbeveelt) om je Liquid voor elke implementatie te valideren.

Een opmerking over de Instagram In-App Browser Bug (juni 2026)

Een live probleem dat je moet weten: vanaf de week van 14 juni 2026 hebben meerdere Horizon-handelaren gerapporteerd dat verder navigeren na het initiële paginaberichten in de in-app browsers van Instagram, Facebook en TikTok een wit scherm produceert. Shopifys themateam erkende het probleem op 17 juni 2026, bevestigde dat een workaround bestaat, en zei dat de onderliggende oorzaak gerelateerd kan zijn aan in-app browser-gedrag in plaats van het thema zelf. Als je social commerce-campagnes hebt die verkeer via deze in-app browsers stuurt, neem contact op met Shopify Support voor de huidige workaround terwijl de volledige fix in behandeling is.

Samenvatting: Het juiste mentale model voor Horizons winkelwagen

Stop met zoeken naar main-cart-items.liquid. Het is een Dawn-concept. Horizons winkelwagen is:

• Een buitensectie: main-cart.liquid
• Een interactieve webcomponent: <cart-items-component> die Ajax-herweergave afhandelt
• Een voettekstsectie: main-cart-footer.liquid voor winkelwagen-attributen en het afrekenen-formulier
• Blokkenmap: waar al je aangepaste toevoegingen wonen

Werk binnen dat model, beheer je wijzigingen via een goede GitHub upstream-tak, en je kunt Horizons winkelwagen veilig aanpassen zonder voor elke wekelijkse update bang te zijn.

Als je handmatige hulp nodig hebt bij het bouwen van een aangepaste winkelwagenervaaring op Horizon, zie wat we doen als Shopify thema-ontwikkelaar of controleer onze Shopify snelheidsoptimalisatie service als winkelwagenprestatie het onderliggende probleem is.