group_by Modifier

Overview

You may use this modifier to group items (a simple array, a collection of entries, etc) into groups
based on some common value.

By Key

The most basic usage example would be to take a simple array and output the groups using the key.

sponsors:
  -
    sport: basketball
    team: Jazz
  -
    sport: baseball
    team: Yankees
  -
    sport: basketball
    team: Bulls

{{ sponsors | group_by('sport') }}
  <h1>Basketball</h2>
  {{ basketball }}
    {{ team }}
  {{ /basketball }}
 
  <h1>Baseball</h2>
  {{ baseball }}
    {{ team }}
  {{ /baseball }}
{{ /sponsors }}

<h1>Basketball</h1>
Jazz
Bulls
 
<h1>Baseball</h1>
Yankees

Looping Over Groups

In the previous example, you had to know that there was going to be basketball and baseball keys ahead of time.

If you don't know the groups, you can loop over the groups variable.
It will be an array containing the name of the group and its items.

{{ sponsors group_by="sport" }}
    {{ groups }}
        <h1>{{ group | upper }}</h1>
        {{ items }}
            {{ team }}
        {{ /items }}
    {{ /groups }}
{{ /sponsors }}

Nested Values

If you need to get a nested value for the groups, you can use the familiar colon syntax.

For example, you may have an entries field where you've selected entries from multiple collections, and you want to group by the collection's title.

menu_items:
  - burger
  - fries
  - coke
  - pepsi

{{ menu_items group_by="collection:title" }}
    {{ groups }}
        <h2>{{ group }}</h2>
        {{ items }}
            {{ title }}
        {{ /items }}
    {{ /groups }}
{{ /menu_items }}

<h2>Food</h2>
Burger
Fries
 
<h2>Drinks</h2>
Coke
Pepsi

Dates

You may group entries by a date field.

For example, you might want to output articles and group them by month.

Here we'll group them by the date field using the F Y PHP date format which
would output as "Month Year".

{{ collection:articles as="entries" }}
    {{ entries group_by="date|F Y" }}
        {{ groups }}
            <h1>{{ group }}</h1>
            {{ items }}
                {{ title }}
            {{ /items }}
        {{ /groups }}
    {{ /entries }}
{{ /collection:articles }}

<h1>September 2021</h1>
Entry from September
Another entry from September
 
<h1>October 2021</h1>
Entry from October

{{ entries group_by="custom_date_field|F Y" }}

If you need the key to differ from how it's displayed (perhaps you want to use an additional modifier after), you can pass another date format as the
third argument. (Argument 2 creates the key, argument 3 creates the {{ group }} text).

{{ entries group_by="date|Y-m|F Y" }}