# 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).

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

#### Syntax

```liquid
{{ 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:**

```liquid
{% 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:**

```liquid
{% 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:**

```liquid
{% 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:**

```liquid
{% 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`