group_by

Groups an array of objects by a property value. Returns an array of groups, each with a name (the property value) and items (array of matching objects).

{% assign grouped = products | group_by: "vendor" %}
{% for group in grouped %}
  {% log group.name | append: ": " | append: group.items.size | append: " products" %}
{% endfor %}

Syntax

{{ array | group_by: property }}

Parameter	Description
array	Array of objects to group
property	Property name to group by (supports nested properties via dot notation)

Return Value

Returns an array of group objects:

Property	Type	Description
name	any	The property value shared by all items in this group
items	Array	Array of items that have this property value

Examples

Group orders by status:

{% assign grouped = orders | group_by: "financial_status" %}
{% for group in grouped %}
  {% log group.name | append: ": " | append: group.items.size | append: " orders" %}
{% endfor %}

Output:

paid: 42 orders
pending: 7 orders
refunded: 3 orders

Group products by vendor and process each group:

{% assign by_vendor = products | group_by: "vendor" %}
{% for group in by_vendor %}
  {% log "Processing vendor: " | append: group.name %}
  {% for product in group.items %}
    {% log "  - " | append: product.title %}
  {% endfor %}
{% endfor %}

Group by nested property:

{% assign by_country = orders | group_by: "shipping_address.country" %}
{% for group in by_country %}
  {% log group.name | append: ": " | append: group.items.size | append: " orders" %}
{% endfor %}

Count items per group:

{% assign by_type = products | group_by: "product_type" %}
{% for group in by_type %}
  {% if group.items.size > 10 %}
    {% log group.name | append: " has " | append: group.items.size | append: " products" %}
  {% endif %}
{% endfor %}

Notes

• Groups are returned in the order their keys are first encountered

• Supports dot notation for nested properties: "node.status", "address.city"

• For grouping with complex expressions, use group_by_exp

• For faster performance with direct key access, use group_by_property or group_by_fast

• See also: group_by_exp, group_by_property, group_by_fast