load_products

Tag `{% load_products %}`

Sintaxe: {% load_products ... %} Variável de output: {{ products }} — array de objetos product Contexto: disponível em qualquer template de página

Essa tag lista produtos da loja.

Para utilizá-la você deve passar uma série de parâmetros como input.

O output da tag é uma lista de produtos na array {{ products }} com os objetos {{ product }} com as informações de cada produto.

Os produtos do array de output podem ser acessados através de um loop for.

Essa tag pode ser usada em qualquer template de página.

input:

{% load_products tag:tag.name %}

{% for product in products %}
  {{ product.name }}
{% endfor %}

output:

Camiseta Verão
Casaco Outono
Blusão Inverno
Saia Primavera

Parâmetros

A tag load_products possui parâmetros principais e parâmetros de filtro. Depois desta seção, há uma explicação separada sobre a API de busca de produtos e sua relação com a listagem da vitrine.

Parâmetros principais

tag: recebe o [nome identificador]({%- link docs/liquid4/objetos/tag.md -%}#name) da tag.

{% load_products tag:tag.name %}

q: recebe os termos de busca informados pelo cliente.

<form action="{{ search_url }}" method="get">
  <input type="search" name="search_query" />
</form>

{% getparam "search_query" as params_search_query %}

{% load_products q: params_search_query %}

Na documentação técnica da busca interna da plataforma, esse mesmo papel pode aparecer descrito como busca por termo textual. Na vitrine, o ponto de entrada documentado para esse comportamento continua sendo o parâmetro q.

📘

É obrigatório o uso parâmetro tag ou q dependendo da lista de produtos.

Saiba mais sobre como ter acesso aos parâmetros de URL no artigo Objetos e como criar um formulário de busca no artigo search.liquid

ids: carrega produtos específicos. Para isso utilize de input os ids dos produtos separados por vírgula.

{% load_products ids: '1, 2, 3, 4, 5' %}

parent_tag: A tag “pai” da lista de produtos.

Considere que o cliente está acessando o seguinte endereço:

https://demo.vnda.com.br/camisetas/algodao/

Ele está vendo uma lista de produtos que tenham a tag camisetas e, desses, os que possuem a tag algodao. Para respeitar ambas as tags, é preciso usar o parâmetro parent_tag.

{% load_products tag:tag.name parent_tag:parent_tag.name %}

per_page:

O parâmetro per_page controla a quantidade de produtos exibidos por página na lista de produtos. A quantidade padrão de produtos por página é 25.

É possível permitir que o cliente delimite quantos produtos devem ser exibidos por página usando a tag {% raw %}{{ getparam }}{% endraw %}.

{% getparam 'per_page' as per_page %}

{% load_products q:search_query per_page:per_page %}

sort

O parâmetro sort define a ordenação dos produtos na lista.

Veja a documentação do objeto {% raw %}{{ sort_options }}{% endraw %} para mais informações sobre como criar opções de ordenação de produtos para o cliente.

{% getparam "sort_by" as params_sort_by %}

{% load_products q: params_search_query sort: params_sort_by %}

Na lógica de busca da plataforma, a ordenação final pode combinar mais de um critério. Em geral, a listagem considera disponibilidade, a ordenação selecionada e, em alguns contextos, critérios internos de relevância.

Valores usuais de ordenação:

newest
oldest
highest_price
lowest_price
az
za

Parâmetros de filtro

Você pode criar filtros para que os clientes selecionem os parâmetros que devem delimitar exibição da lista de produtos.

Filtros são feitos com as informações agregadas de todos os produtos da lista, disponíveis através do objeto {% raw %}{{ aggregations }}{% endraw %}. Para permitir que o cliente tenha acesso às opções de filtro, é necessário criar um formulário HTML no tag.liquid e de search.liquid:

<form action="{{ current_url }}" method="get">
  <h3>Filtro de materiais:</h3>

  {% for material in aggregations.types.material %}
    <p>
      <input id="material_{{ forloop.index }}" type="checkbox" name="type_tags[material][]" value="{{ material.name }}" />
      <label for="material_{{ forloop.index }}">{{ material.title }}</label>
    </p>
  {% endfor %}
</form>

Nesse caso criamos uma lista com todas as tags do tipo material que são relacionadas aos produtos na lista de produtos atual.

Para filtros de tipos de tag, o name do input deve ser type_tags[tipodatag][]. E para filtros de propriedades, o name do input deve ser property1_values[] ou property2_values[] ou property3_values[]

Existem vários filtros que podem ser usados, seja de maneira dinâmica (com o cliente definindo seus valores) ou de maneira estática, com o desenvolvedor definindo-os no código.

Para facilitar a implementação dos filtros, os templates possuem já configurado o Componente de Filtros, que pode ser expandido para exibir mais opções de filtro do que os templates adicionam por padrão.

min_price: delimita um filtro de preço mínimo para a lista de produtos.

{% load_products tag:tag.name min_price:params.min_price %}

max_price: delimita um filtro de preço máximo para a lista de produtos.

{% load_products tag:tag.name max_price:params.max_price %}

exclude_tags: impede a exibição de produtos que contenham a tag informada nesse parâmetro.

Esse parâmetro é útil quando a listagem precisa excluir produtos que participam de uma mesma coleção de navegação, mas que não devem ser exibidos naquele contexto específico.

{% load_products tag:tag.name exclude_tags: 'nao-exibir' %}

No exemplo acima, a listagem continua sendo feita a partir da tag atual, mas produtos que possuam a tag nao-exibir deixam de ser exibidos.

type_tags: representa filtros organizados por tipo de tag.

Na implementação de vitrine, esse parâmetro normalmente é alimentado por formulários com nomes no formato type_tags[tipodatag][].

<input type="checkbox" name="type_tags[cor][]" value="azul" />
<input type="checkbox" name="type_tags[tamanho][]" value="m" />

Conceitualmente, isso equivale a enviar uma estrutura agrupada por tipo de tag para a listagem atual.

type_tags_operator: define o operador lógico que filtra as tags do mesmo tipo, se aplica a todos os tipos de tags. Possui dois valores possíveis:
OR (padrão) — o produto precisa ter qualquer uma das tags selecionadas para ser exibido.
AND — o produto precisa ter todas as tags selecionadas para ser exibido.

{% load_products tag: tag.name type_tags_operator: "and" %}

property1_values[], property2_values[] e property3_values[]: filtram a listagem pelos valores das propriedades das variantes.

{% load_products tag: tag.name property1_values: params.property1_values property2_values: params.property2_values %}

Esse tipo de filtro costuma ser usado para atributos como tamanho, cor ou outros valores cadastrados nas variantes.

Referência da API de busca de produtos

Esta seção resume a documentação de referência da busca de produtos da plataforma que você enviou como material complementar.

Ela não substitui o contrato documentado da tag {% load_products %}. Em vez disso, ela explica a lógica de busca que fica por trás de muitas listagens da vitrine e ajuda a entender como a plataforma organiza:

Termos de busca
Paginação
Ordenação
Filtros
Agregações

Use esta parte como uma referência da API e da lógica interna de busca de produtos.

Use as seções anteriores como referência do que está documentado aqui como uso direto do load_products em templates Liquid.

Em outras palavras:

A seção acima documenta a tag {% load_products %}
A seção abaixo documenta a busca de produtos da plataforma em um nível mais amplo
Os conceitos se relacionam, mas não devem ser tratados automaticamente como equivalentes

O que esta referência cobre

Na documentação de referência da busca, a listagem de produtos pode combinar:

Termos textuais
Paginação
Ordenação
Filtros por tags
Filtros por propriedades de variante
Filtros por disponibilidade
Agregações para montar interfaces dinâmicas de filtro

Nessa referência, o retorno é descrito como uma coleção de produtos acompanhada por dados agregados que ajudam a construir filtros e refinar a navegação.

Parâmetros principais da API de busca

Parâmetro	Tipo	Descrição
`term`	string	Busca por um termo textual. Na vitrine Liquid, esse papel costuma corresponder ao uso de `q`.
`page`	integer	Número da página de resultados.
`per_page`	integer	Quantidade de resultados por página.
`sort`	string	Define a ordenação da lista.
`ids`	array	Restringe a busca a uma lista específica de IDs de produto.

Como a ordenação é descrita na referência da busca

Na referência da busca que você enviou, a ordenação pode considerar mais de um critério ao compor a lista final. Em geral, o resultado pode refletir:

Disponibilidade dos produtos
Critério de ordenação solicitado
Relevância, especialmente em buscas textuais

Valores usuais de ordenação:

newest
oldest
highest_price
lowest_price
az
za

Quando a consulta depende de termo textual e nenhum critério explícito é informado, a plataforma pode priorizar relevância como ordenação padrão.

Parâmetros de filtragem da API de busca

Parâmetro	Tipo	Descrição
`tags`	array	Filtra produtos por tags adicionais.
`parent_tags`	array	Complementa o conjunto de tags usadas no filtro.
`tags_operator`	string	Define a lógica entre `tags` e `parent_tags`.
`exclude_tags`	array	Exclui produtos que possuam determinadas tags.
`type_tags`	hash	Filtra produtos por tipos de tag.
`type_tags_operator`	string	Define a lógica do filtro de `type_tags`.
`property1_values`	array	Filtra pelo primeiro atributo de variante.
`property2_values`	array	Filtra pelo segundo atributo de variante.
`property3_values`	array	Filtra pelo terceiro atributo de variante.
`property1_operator`	string	Define a lógica dos valores em `property1_values`.
`property2_operator`	string	Define a lógica dos valores em `property2_values`.
`property3_operator`	string	Define a lógica dos valores em `property3_values`.
`min_price`	float	Define o preço mínimo inclusivo.
`max_price`	float	Define o preço máximo inclusivo.
`places`	array	Restringe a busca a produtos com estoque em locais específicos.
`show_inactive`	string	Inclui produtos inativos.
`show_only_available`	string	Restringe o retorno a produtos disponíveis.

Operadores lógicos na busca

Alguns grupos de filtro aceitam operadores lógicos para refinar o comportamento:

OR: o produto precisa corresponder a pelo menos um dos valores informados
AND: o produto precisa corresponder a todos os valores informados

Isso vale, por exemplo, para:

tags_operator
type_tags_operator
property1_operator
property2_operator
property3_operator

Parâmetros avançados da API de busca e agregação

Parâmetro	Tipo	Descrição
`term_fields`	array	Define em quais campos o termo textual deve ser procurado.
`term_operator`	string	Define a lógica entre múltiplas palavras do termo buscado.
`types`	array	Solicita agregações para tipos de tag específicos.
`price_ranges`	array	Define faixas de preço personalizadas para agregação.
`agg_tags_size`	integer	Limita a quantidade de tags retornadas nas agregações.
`agg_properties_size`	integer	Limita a quantidade de valores retornados nas propriedades agregadas.
`agg_types_size`	integer	Limita a quantidade de valores retornados por tipo nas agregações.

Busca textual na referência da API

Na referência da busca, term_fields permite restringir onde o termo deve ser analisado. Dependendo da implementação, isso pode incluir campos como:

Nome do produto
Descrição
SKU

Já term_operator define como múltiplas palavras devem ser interpretadas:

OR: qualquer palavra pode gerar correspondência
AND: todas as palavras precisam estar presentes

O que a API de busca retorna

Além da lista de produtos, a busca pode devolver dados agregados sobre o conjunto de resultados atual.

Essas agregações são importantes para montar interfaces como:

Filtrar por cor
Filtrar por tamanho
Filtrar por categoria
Filtrar por faixa de preço

Na prática, isso se conecta diretamente com o uso de {{ aggregations }} na vitrine.

Relação entre a referência da busca e o `load_products`

Embora a tag {% load_products %} seja o ponto de entrada documentado para uso em templates Liquid, parte do comportamento observado na vitrine reflete essa lógica de busca mais ampla.

Algumas relações úteis:

Contexto da listagem Liquid	Conceito equivalente na busca
`q`	`term`
`tag` / `parent_tag`	filtros de navegação por tags
`type_tags[...][]`	`type_tags`
`property1_values[]`, `property2_values[]`, `property3_values[]`	filtros por propriedades de variante
`sort`	ordenação da busca
`per_page`	paginação da busca
`aggregations`	dados agregados do conjunto de resultados

Como usar esta separação na documentação

Ao trabalhar com load_products, é útil separar duas coisas:

O que está efetivamente estabelecido como uso da tag em templates Liquid.
O que faz parte da lógica mais ampla da busca de produtos da plataforma.

Essa distinção evita tratar automaticamente todos os parâmetros da busca como se fossem contrato público da tag.

Como a busca é interpretada

Quando {% load_products %} é usada em contextos de busca, como no template search.liquid, a plataforma pode aplicar regras internas de relevância, disponibilidade e ordenação para compor a lista final.

De forma geral:

O parâmetro q define o termo de busca informado pelo cliente.
O parâmetro sort altera a ordenação da listagem.
Quando a listagem usa um termo textual, a plataforma pode priorizar relevância como critério padrão.
A disponibilidade dos produtos também pode influenciar a ordem final exibida na vitrine.

Na prática, isso significa que a lista retornada não depende apenas do termo buscado, mas também das regras de ordenação e disponibilidade aplicadas pela plataforma.

Cenários de uso mais comuns

Além dos exemplos de parâmetros, é útil pensar na tag {% load_products %} a partir do tipo de listagem que você precisa montar na vitrine.

Os cenários mais comuns são:

Listagem por tag: usado em páginas como tag.liquid, quando a vitrine precisa exibir produtos relacionados a uma tag atual.
Resultados de busca: usado em search.liquid, quando a listagem depende dos termos digitados pelo cliente.
Carregamento pontual por IDs: usado quando a vitrine já conhece previamente quais produtos devem ser carregados, como em kits nativos da plataforma ou composições específicas.

Implementações de exemplo

Os exemplos abaixo mostram duas implementações comuns de {% load_products %}: uma para listagem por tag e outra para resultados de busca.

Exemplo de listagem por tag

Essa implementação usa a tag atual da página para carregar os produtos, aplica ordenação, paginação e mantém o uso de filtros por tipo de tag.

{% getparam 'sort' as params_sort %}

{% load_products tag: tag.name parent_tag: parent_tag.name per_page: 24 sort: params_sort type_tags_operator: "and" %}

{% capture html_products %}
  {% for product in products %}
    <a href="{{ product.url }}">{{ product.name }}</a>
  {% endfor %}
{% endcapture %}

{% if html_products == blank %}
  <p>Nenhum produto encontrado para esta tag.</p>
{% else %}
  {{ html_products }}
{% endif %}

{% if pagination.total_pages > 1 %}
  {% if pagination.prev_url %}
    <a href="{{ pagination.prev_url }}" rel="prev">Página anterior</a>
  {% endif %}

  {% if pagination.next_url %}
    <a href="{{ pagination.next_url }}" rel="next">Próxima página</a>
  {% endif %}
{% endif %}

Nesse tipo de implementação:

tag e parent_tag definem o contexto da listagem
sort altera a ordenação dos itens
per_page limita a quantidade de produtos por página
pagination permite navegar entre as páginas da listagem

Exemplo de listagem por busca

Essa implementação usa o termo buscado pelo cliente e combina filtros por tipo, propriedades de variante e faixa de preço.

{% getparam 'sort' as params_sort %}
{% getparam 'type_tags' as params_type %}
{% getparam 'property1_values' as params_property1 %}
{% getparam 'property2_values' as params_property2 %}
{% getparam 'property3_values' as params_property3 %}
{% getparam 'q' as params_search %}
{% getparam 'min_price' as params_min_price %}
{% getparam 'max_price' as params_max_price %}

{% unless params_property1 %}
  {% assign params_property1 = '' %}
{% endunless %}

{% unless params_property2 %}
  {% assign params_property2 = '' %}
{% endunless %}

{% unless params_property3 %}
  {% assign params_property3 = '' %}
{% endunless %}

{% unless params_type %}
  {% assign params_type = '' %}
{% endunless %}

{% unless params_min_price %}
  {% assign params_min_price = 0.01 %}
{% endunless %}

{% unless params_max_price %}
  {% assign params_max_price = 999999 %}
{% endunless %}

{% if params_search != blank %}
  {% load_products q: params_search per_page: 24 type_tags: params_type sort: params_sort property1_values: params_property1 property2_values: params_property2 property3_values: params_property3 min_price: params_min_price max_price: params_max_price type_tags_operator: "and" %}

  {% if products.size > 0 %}
    {% for product in products %}
      <a href="{{ product.url }}">{{ product.name }}</a>
    {% endfor %}
  {% else %}
    <p>Nenhum produto encontrado para a busca atual.</p>
  {% endif %}
{% else %}
  <p>Informe um termo para iniciar a busca.</p>
{% endif %}

Nesse tipo de implementação:

q recebe o termo buscado pelo cliente
type_tags aplica filtros por tipos de tag
property1_values, property2_values e property3_values refinam a busca pelas propriedades das variantes
min_price e max_price limitam a faixa de preço dos resultados
products contém a lista final retornada pela busca

Objetos populados pela tag

Ao executar {% load_products %}, a plataforma não disponibiliza apenas o array {{ products }}. A chamada também pode popular outros objetos usados para enriquecer a experiência de navegação na listagem.

Objeto	Função
`{{ products }}`	Lista de produtos retornados pela consulta atual.
`{{ aggregations }}`	Dados agregados da listagem, usados para filtros por tags, propriedades e faixas de preço.
`{{ pagination }}`	Informações para navegação entre páginas da listagem.
`{{ sort_options }}`	Opções de ordenação disponíveis para a listagem atual.

Em páginas de listagem, esses objetos normalmente trabalham juntos: {{ products }} renderiza os itens, {{ aggregations }} alimenta os filtros, {{ sort_options }} controla a ordenação e {{ pagination }} permite navegar entre páginas.

Relação entre parâmetros da tag e parâmetros de URL

Em grande parte das implementações, {% load_products %} recebe valores vindos de formulários HTML e dos parâmetros da URL atual. Isso é o que permite que filtros, ordenação e paginação reajam à navegação do cliente.

Veja alguns exemplos frequentes:

Parâmetro em `{% load_products %}`	Origem comum	Finalidade
`q`	campo de busca	Buscar produtos a partir de um termo digitado pelo cliente.
`sort`	`<select>` de ordenação	Alterar a ordem da listagem.
`per_page`	parâmetro numérico	Definir quantos produtos devem ser exibidos por página.
`min_price` / `max_price`	campos de filtro	Limitar a faixa de preço da listagem.
`type_tags[...][]`	checkboxes ou múltipla escolha	Filtrar produtos por tags organizadas por tipo.
`property1_values[]`, `property2_values[]`, `property3_values[]`	checkboxes ou múltipla escolha	Filtrar produtos por propriedades cadastradas nos produtos.

Esse fluxo é especialmente comum nos templates de listagem por tag e de resultados de busca.

Fluxo completo de uma listagem de produtos

Em uma implementação típica, a tag {% load_products %} participa do fluxo abaixo:

O template define o contexto da listagem, como tag, q ou ids.
A plataforma retorna os produtos em {{ products }}.
A mesma chamada disponibiliza {{ aggregations }} para montagem dos filtros.
Também disponibiliza {{ sort_options }} para a ordenação da listagem.
Quando há mais resultados do que o limite da página, {{ pagination }} permite navegar entre as páginas seguintes.

Esse fluxo aparece com mais frequência em páginas de categoria, páginas de busca e outras vitrines que precisam reagir a filtros e ordenação do cliente.

Caso especial: carregamento por IDs

Além dos cenários de listagem por tag e busca, {% load_products %} também pode ser usada para carregar um conjunto conhecido de produtos a partir de IDs.

Esse uso é útil quando o template já possui previamente a lista de produtos que precisa renderizar. Um exemplo prático está na implementação de kits nativos da plataforma, em que os IDs dos produtos internos são montados antes da chamada:

{% load_products ids: bundle_product_ids %}

Nesse tipo de cenário, a tag deixa de depender de uma listagem aberta por navegação e passa a funcionar como uma forma de hidratar um conjunto específico de produtos no template.

Produtos indisponíveis na listagem

Em implementações de listagem, é importante considerar como a plataforma trata produtos indisponíveis.

Por padrão, a chamada de {% load_products %} pode trazer também produtos indisponíveis. Quando a vitrine precisa exibir somente itens disponíveis para compra, essa regra pode depender de configuração da plataforma e do comportamento adotado na loja.

Se a sua implementação inclui filtros visuais, grids de categoria ou páginas de busca, vale validar esse comportamento junto às configurações utilizadas no projeto antes de assumir que a listagem exibirá apenas produtos disponíveis.

Referências relacionadas

Para complementar a implementação de {% load_products %}, consulte também: