Shopify Liquid: La Guida Definitiva per Commercianti e Sviluppatori

Shopify Liquid è il linguaggio di templating open-source che alimenta ogni vetrina Shopify. Connette i dati del backend del tuo negozio (prodotti, collezioni, carrello, cliente) all'HTML che i tuoi clienti vedono, utilizzando tre primitivi: oggetti, tag e filtri. Usare correttamente questi tre elementi fa la differenza tra un tema che converte e uno che ti costa soldi ogni mese in abbonamenti a app e ticket di supporto.

Punti chiave

• I tre primitivi di Liquid sono oggetti {{ }}, tag {% %} e filtri |. Ogni personalizzazione che fai su un tema Shopify passa attraverso questi tre.
• Il tag {% render %} ha sostituito {% include %} nel 2019 ed è l'unico tag di inclusione supportato da Online Store 2.0. Fare lo swap tra i due è ancora il guadagno di performance più veloce sui temi legacy.
• I nuovi filtri aggiunti nel 2025-2026 includono image_tag con attributi fetchpriority e sizes, e metafield_tag per il rendering strutturato di metafield.
• Un loop collezione non ottimizzato con controlli tag annidati può aggiungere 2-4 secondi a LCP e costa circa il 7% delle entrate mobile per ogni secondo più lento.
• Sostituire 3-5 app di livello medio con sezioni Liquid native di solito fa risparmiare 100-300 dollari al mese e rimuove 150-600 KB di JavaScript di terze parti per pagina.

Cos'è Shopify Liquid?

Liquid è un linguaggio di template che ti consente di creare un singolo template per ospitare contenuti statici e inserire dinamicamente informazioni a seconda di cosa viene visualizzato. Un template di prodotto, per esempio, contiene tutti i tuoi attributi di prodotto standard e scambia dinamicamente il contenuto corretto per ogni URL di prodotto.

La variante Shopify di Liquid estende la versione open-source con oggetti specifici del negozio (product, collection, cart, customer, shop) e filtri costruiti per il commercio (money, image_url, metafield_tag). A partire dal 13 gennaio 2026, Shopify ha anche aggiornato il modo in cui elabora internamente il codice Liquid per rendere il rendering dei temi più affidabile, senza azioni richieste ai commercianti.

I tre primitivi

1. Oggetti

Gli oggetti emettono dati dinamici usando doppie graffe:

{{ product.title }}
{{ product.price | money }}
{{ shop.name }}

Oggetti globali chiave che utilizzerai in ogni costruzione di tema:

Gli oggetti possono rappresentare un valore singolo o esporre più proprietà. L'oggetto request è particolarmente utile per il rendering condizionale basato sul tipo di pagina.

2. Tag

I tag aggiungono logica e controllo di flusso usando la sintassi {% %}. Le categorie che devi conoscere:

Controllo di flusso liquid {% if product.available %} <button>Aggiungi al carrello</button> {% else %} <button disabled>Esaurito</button> {% endif %}

Iterazione liquid {% for product in collection.products limit: 24 %} {% render 'product-card', product: product %} {% endfor %}

Assegnazione di variabili liquid {% assign sale_price = product.compare_at_price | minus: product.price %} {% capture button_label %}Aggiungi {{ product.title }}{% endcapture %}

Tag di tema (sezioni, snippet, layout) liquid {% render 'product-card', product: product, show_vendor: true %} {% section 'announcement-bar' %} {% layout 'checkout' %}

3. Filtri

I filtri modificano l'output usando il carattere pipe |. Più filtri si collegano da sinistra a destra:

{{ product.title | upcase | truncate: 50 }}
{{ product.price | money }}
{{ product.featured_image | image_url: width: 800 | image_tag: loading: 'lazy', widths: '200,400,600,800' }}

Categorie di filtri critici:

• Filtri denaro: | money, | money_with_currency, | money_without_trailing_zeros. Non codificare mai i simboli di valuta. Il filtro | money rispetta le impostazioni di valuta, locale e formattazione del tuo negozio. Un simbolo $ codificato infrange il momento in cui abiliti multi-valuta in Shopify Markets.
• Filtri immagine: | image_url: width: X seguito da | image_tag. I moderni filtri image_url e image_tag hanno sostituito i vecchi img_url e img_tag e forniscono immagini responsive con srcset, sizes, lazy loading e attributi fetchpriority in una singola catena.
• Filtri array: | where, | map, | sort, | uniq, | join, | concat. Usa | where per filtrare array senza loop.
• Filtri stringa: | upcase, | downcase, | truncate, | strip_html, | escape, | split.
• Filtri matematici: | plus, | minus, | times, | divided_by, | ceil, | floor, | round.
• Filtri colore: | color_lighten, | color_darken, | color_mix, | color_contrast. Il filtro color_contrast restituisce il rapporto di contrasto tra due colori, essenziale per il design accessibile di badge e pulsanti.
• Filtri localizzazione: | t (traduzione), | format_address, | currency_selector.

Una nota sul trucco | where: il filtro fa distinzione tra maiuscole e minuscole. | where: 'tags', 'Sale' non corrisponderà a un tag di 'sale'. Usa | downcase prima del confronto.

Sezioni e il tag {% schema %}

Online Store 2.0 ha reso le sezioni disponibili ovunque, non solo sulla homepage. Ogni sezione che costruisci dovrebbe avere un blocco {% schema %} completo in modo che i commercianti possano modificare i contenuti dall'editor del tema senza aprire un file di codice.

Ogni sezione può avere un solo tag {% schema %}, che deve contenere JSON valido. Averne più di uno, o annidarlo all'interno di un altro tag Liquid, produce un errore di sintassi.

Uno schema di sezione minimo ma completo:

{% schema %}
{
  "name": "Feature banner",
  "tag": "section",
  "settings": [
    {
      "type": "text",
      "id": "heading",
      "label": "Heading",
      "default": "Our promise"
    },
    {
      "type": "image_picker",
      "id": "image",
      "label": "Background image"
    }
  ],
  "blocks": [
    {
      "type": "feature",
      "name": "Feature item",
      "settings": [
        { "type": "text", "id": "feature_text", "label": "Feature", "default": "Free shipping" }
      ]
    }
  ],
  "max_blocks": 4,
  "presets": [{ "name": "Feature banner" }]
}
{% endschema %}

Regola critica: tratta i valori id di impostazione come nomi di colonne di database. Diventano chiavi persistenti nel JSON di template in ogni negozio che installa la tua sezione. Rinominare un id rende orfani i valori esistenti. Cambiare un'impostazione text in image_picker non migra i dati. Utilizza i prefissi quando le sezioni crescono: usa hero_heading piuttosto che heading se hai anche card_heading nei blocchi.

Le sezioni con preset non dovrebbero essere sottoposte a rendering statico. Le sezioni sottoposte a rendering statico non possono essere rimosse o riordinate dai commercianti.

Il tag {% render %} (e perche {% include %} è morto)

Il tag {% render %} è l'unico modo per includere snippet nei moderni temi Shopify. {% include %} condivideva l'ambito della variabile tra snippet, il che causava conflitti di naming e rendeva la profilazione delle performance inaffidabile. {% render %} crea un ambito isolato: gli snippet non possono leggere le variabili parent a meno che non siano passate in come parametri denominati.

{# DEPRECATED - shares parent scope #}
{% include 'product-card' %}

{# CORRECT - isolated scope, explicit inputs #}
{% render 'product-card', product: product, show_vendor: true %}

{# Loop form #}
{% render 'product-card' for collection.products as product %}

L'ambito isolato significa che gli snippet sono facilmente riutilizzabili su pagine di dettaglio prodotto, risultati di ricerca, risposte del carrello AJAX e richieste Section Rendering API senza riscritture. Sostituire {% include %} con {% render %} cancella anche ogni errore di Theme Check che blocca l'invio allo Shopify Theme Store.

Metafield in Liquid

I metafield ti consentono di estendere il modello di dati di Shopify con dati personalizzati (tabelle di taglie, ingredienti, istruzioni di cura, specifiche) senza app. I tipi di metafield più potenti per lo sviluppo Liquid sono:

• JSON per dati strutturati (renderizzare con | metafield_tag o analizzare il valore)
• Testo ricco per copie del corpo HTML modificabili dal commerciante
• Riferimento file per immagini e video allegati ai prodotti
• Riferimento prodotto/collezione per relazioni esplicite tra risorse

Modello di accesso:

{% assign size_chart = product.metafields.custom.size_chart %}
{% if size_chart != blank %}
  {{ size_chart.value | metafield_tag }}
{% endif %}

La protezione != blank è non negoziabile. Saltarla e i prodotti senza una tabella di taglie renderizzano una <table> vuota che causa il crash del layout su mobile Safari.

Crea sempre definizioni di metafield tramite Impostazioni > Dati personalizzati nell'admin Shopify, mai al volo tramite API. Le definizioni ti danno convalida del tipo, etichette amichevoli al commerciante e visibilità nell'admin. App di terze parti come Yotpo e Klaviyo leggono queste definizioni, quindi uno schema pulito alimenta il resto del tuo stack.

Pattern di performance che contano veramente

Ottimizzazione loop

I loop annidati sono il killer di performance più comune nei temi Liquid che audito. Un loop esterno su 50 prodotti combinato con un loop interno su 20 tag per prodotto esegue 1.000 iterazioni per rendering di pagina. Usa invece l'operatore contains:

{# BAD: O(n*m) - 50 products x 20 tags = 1,000 iterations #}
{% for product in collection.products %}
  {% for tag in product.tags %}
    {% if tag == 'featured' %}...{% endif %}
  {% endfor %}
{% endfor %}

{# GOOD: one pass, contains check is O(1) #}
{% for product in collection.products limit: 24 %}
  {% if product.tags contains 'featured' %}...{% endif %}
{% endfor %}

Aggiungi sempre limit: ai loop di collezione. Un loop non ottimizzato può aggiungere 2-4 secondi a LCP su mobile.

Rendering dell'immagine

{# BAD: no dimensions, no srcset, browser cannot reserve space (CLS) #}
<img src="{{ product.featured_image | img_url: 'master' }}">

{# GOOD: srcset, lazy loading, explicit width hint #}
{{ product.featured_image
  | image_url: width: 800
  | image_tag:
      loading: 'lazy',
      widths: '200,400,600,800',
      sizes: '(min-width: 768px) 400px, 100vw',
      alt: product.title }}

Il filtro image_tag fa in una riga quello che in precedenza richiedeva tre righe di HTML con costruzione manuale di srcset.

Controllo degli spazi bianchi

Liquid emette spazi bianchi intorno a ogni tag. Su template di grandi dimensioni questo gonfia l'HTML e rallenta TTFB. Usa il modificatore - per rimuoverlo:

{%- for product in collection.products -%}
  {{- product.title -}}
{%- endfor -%}

Section Rendering API

La Section Rendering API consente il rendering indipendente delle sezioni tramite AJAX, abilitando transizioni di pagina più veloci e aggiornamenti dinamici del carrello senza ricaricamenti di pagina completi. Questo è il fondamento per esperienze simili a app all'interno di temi Liquid standard, senza l'overhead di passare a headless.

Theme Check e tooling

Theme Check 2.0 è ora integrato in Shopify CLI e cattura problemi di performance, problemi di accessibilità e utilizzo di pattern deprecati prima del deploy. Eseguilo ad ogni commit. Individua:

• Chiamate {% include %} (deprecate)
• Attributi alt mancanti sui tag immagine
• Utilizzo di img_url (sostituito da image_url)
• Loop senza limit:
• content_for_header mancante in theme.liquid

L'overlay Theme Inspector mostra i tempi di rendering Liquid direttamente sulla tua vetrina, così puoi vedere quali sezioni, snippet e loop sono lenti prima di ottimizzare.

A partire dal 2026, il Dev MCP di Shopify consente anche agli agenti AI di generare codice Liquid validato e scaffoldare schemi di sezione, il che accelera il lavoro boilerplate. Tratta l'output AI come una prima bozza e rivedi sempre per edge case specifici di Shopify.

Sostituzione di app: cosa Liquid può fare nativamente

Sostituire 3-5 app per tema con sezioni Liquid native di solito fa risparmiare 100-300 dollari al mese e rimuove 150-600 KB di JavaScript di terze parti. Il bloat di app costa 40-200 ms per script di terze parti su mobile, che è esattamente l'intervallo che fa scendere i punteggi Lighthouse mobile da 80 a 60.

Funzioni che Liquid gestisce nativamente (nessuna app richiesta):

• Banner di conto alla rovescia con date di fine controllate da schema
• Accordion FAQ con architettura blocco per domanda
• Griglie di testimonianze con valutazioni a stelle e recensioni archiviate in metafield
• Barre add-to-cart appiccicose tramite IntersectionObserver più una sezione prodotto Liquid
• Tabelle di confronto caratteristiche usando metafield JSON
• Slider prima/dopo per immagini con JS vanilla e due impostazioni image-picker

Le sezioni battono le app su tre assi: si rendono prima della paint (nessuno shift di layout), vivono nel repo del tuo tema (il controllo di versione è banale) e espongono impostazioni di schema in modo che i commercianti modifichino il contenuto senza uno sviluppatore.

Liquid vs. Hydrogen: la risposta onesta

Liquid rimane la scelta giusta per la stragrande maggioranza dei negozi Shopify perché fornisce sviluppo più veloce, costi di manutenzione inferiori e accesso completo alla CDN e all'infrastruttura di hosting di Shopify. Headless (Hydrogen/Oxygen) ha senso per i brand con team di frontend dedicati e architetture multi-vetrina complesse.

Scegli headless quando hai un team frontend dedicato, tre o più vetrine che condividono un backend, o un modello di interazione che Liquid non può davvero raggiungere. Per tutti gli altri, la domanda non è "Liquid o Hydrogen" ma "come scrivo Liquid che non mi imbarazza tra due anni?"

Se hai bisogno di aiuto per audit o costruire un tema secondo questi standard, vedi la pagina dei servizi sviluppatore tema Shopify, o esplora ottimizzazione della velocità Shopify se le performance sono il collo di bottiglia specifico.

Foglio di riferimento veloce

Sintassi di output

{{ product.title }}              {# string output #}
{{ product.price | money }}      {# filtered output #}
{{- product.title -}}            {# whitespace stripped #}

Controllo di flusso

{% if %} / {% elsif %} / {% else %} / {% endif %}
{% unless %} / {% endunless %}
{% case product.type %}{% when 'Apparel' %}...{% endcase %}

Loop

{% for item in array limit: 24 offset: 0 %}
  {{ forloop.index }} of {{ forloop.length }}
{% else %}
  No items found.
{% endfor %}

Filtri più usati a colpo d'occhio

| money               {# currency-safe price output #}
| image_url: width: X {# CDN-resized image URL #}
| image_tag           {# full responsive <img> tag #}
| metafield_tag       {# renders metafield value with correct HTML #}
| where: 'key', val   {# filter array without a loop #}
| map: 'property'     {# pluck a property from array of objects #}
| json                {# safe JSON output for script tags #}
| t                   {# translation key lookup #}
| handleize          {# string to URL-safe handle #}
| date: '%B %d, %Y'  {# formatted date output #}

Aggiungi un segnalibro al riferimento Liquid ufficiale insieme a questo post. La documentazione ufficiale copre completamente ogni proprietà di oggetto e parametro di filtro.