Patterns Filter a list

Open this example (Filter a list pattern (example)) in a new window 
<div class="moj-filter-layout">

  <div class="moj-filter-layout__filter">

    <div class="moj-filter">

      <div class="moj-filter__header">

        <div class="moj-filter__header-title">
          <h2 class="govuk-heading-m">Filter</h2>
        </div>

        <div class="moj-filter__header-action">

        </div>

      </div>

      <div class="moj-filter__content">

        <div class="moj-filter__selected">

          <div class="moj-filter__selected-heading">

            <div class="moj-filter__heading-title">
              <h2 class="govuk-heading-m">Selected filters</h2>
            </div>

            <div class="moj-filter__heading-action">
              <p><a class="govuk-link govuk-link--no-visited-state" href="">Clear filters</a></p>
            </div>

          </div>

          <h3 class="govuk-heading-s govuk-!-margin-bottom-0">Colour</h3>

          <ul class="moj-filter-tags">

            <li><a class="moj-filter__tag" href="#"><span class="govuk-visually-hidden">Remove this filter</span> Blue</a></li>

            <li><a class="moj-filter__tag" href="#"><span class="govuk-visually-hidden">Remove this filter</span> Yellow</a></li>

          </ul>

          <h3 class="govuk-heading-s govuk-!-margin-bottom-0">Status</h3>

          <ul class="moj-filter-tags">

            <li><a class="moj-filter__tag" href="#"><span class="govuk-visually-hidden">Remove this filter</span> Complete</a></li>

          </ul>

        </div>

        <div class="moj-filter__options">

          <button type="submit" class="govuk-button" data-module="govuk-button">
            Apply filters
          </button>

          <div class="govuk-form-group">
            <label class="govuk-label govuk-label--m" for="keywords">
              Keywords
            </label>

            <input class="govuk-input" id="keywords" name="keywords" type="text">

          </div>

          <div class="govuk-form-group">

            <fieldset class="govuk-fieldset">

              <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">

                Colour

              </legend>

              <div class="govuk-checkboxes govuk-checkboxes--small" data-module="govuk-checkboxes">

                <div class="govuk-checkboxes__item">
                  <input class="govuk-checkboxes__input" id="type" name="type" type="checkbox" value="1" checked>
                  <label class="govuk-label govuk-checkboxes__label" for="type">
                    Blue (18)
                  </label>

                </div>

                <div class="govuk-checkboxes__item">
                  <input class="govuk-checkboxes__input" id="type-2" name="type" type="checkbox" value="2" checked>
                  <label class="govuk-label govuk-checkboxes__label" for="type-2">
                    Yellow (5)
                  </label>

                </div>

                <div class="govuk-checkboxes__item">
                  <input class="govuk-checkboxes__input" id="type-3" name="type" type="checkbox" value="3">
                  <label class="govuk-label govuk-checkboxes__label" for="type-3">
                    Red (2)
                  </label>

                </div>

              </div>

            </fieldset>

          </div>

          <div class="govuk-form-group">

            <fieldset class="govuk-fieldset">

              <legend class="govuk-fieldset__legend govuk-fieldset__legend--m">

                Status

              </legend>

              <div class="govuk-checkboxes govuk-checkboxes--small" data-module="govuk-checkboxes">

                <div class="govuk-checkboxes__item">
                  <input class="govuk-checkboxes__input" id="status" name="status" type="checkbox" value="1" checked>
                  <label class="govuk-label govuk-checkboxes__label" for="status">
                    Complete (5)
                  </label>

                </div>

                <div class="govuk-checkboxes__item">
                  <input class="govuk-checkboxes__input" id="status-2" name="status" type="checkbox" value="2">
                  <label class="govuk-label govuk-checkboxes__label" for="status-2">
                    Incomplete (3)
                  </label>

                </div>

                <div class="govuk-checkboxes__item">
                  <input class="govuk-checkboxes__input" id="status-3" name="status" type="checkbox" value="3">
                  <label class="govuk-label govuk-checkboxes__label" for="status-3">
                    In progress (13)
                  </label>

                </div>

              </div>

            </fieldset>

          </div>

        </div>

      </div>

    </div>

  </div>

  <div class="moj-filter-layout__content">

    <div class="moj-action-bar">

      <div class="moj-action-bar__filter"></div>

      <div class="moj-button-menu">
        <div class="moj-button-menu__wrapper">

          <button type="submit" class="govuk-button moj-button-menu__item govuk-button--secondary " data-module="govuk-button">
            Action 1
          </button>

          <button type="submit" class="govuk-button moj-button-menu__item govuk-button--secondary " data-module="govuk-button">
            Action 2
          </button>

        </div>
      </div>

    </div>

    <div class="moj-scrollable-pane">
      <table class="govuk-table">

        <thead class="govuk-table__head">
          <tr class="govuk-table__row">

            <th scope="col" class="govuk-table__header">Reference</th>

            <th scope="col" class="govuk-table__header">Person</th>

            <th scope="col" class="govuk-table__header">Colour</th>

            <th scope="col" class="govuk-table__header">Status</th>

            <th scope="col" class="govuk-table__header">Date of last event</th>

          </tr>
        </thead>

        <tbody class="govuk-table__body">

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">44455453</a></th>

            <td class="govuk-table__cell">John Smith</td>

            <td class="govuk-table__cell">Blue</td>

            <td class="govuk-table__cell">Complete</td>

            <td class="govuk-table__cell">25 Jan 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">12323212</a></th>

            <td class="govuk-table__cell">Warren Sutton</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">25 Jan 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">45678765</a></th>

            <td class="govuk-table__cell">Alan Jones</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">12345678</a></th>

            <td class="govuk-table__cell">Jennifer Langley</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">89009800</a></th>

            <td class="govuk-table__cell">Susan Francis</td>

            <td class="govuk-table__cell">Red</td>

            <td class="govuk-table__cell">Incomplete</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">44455453</a></th>

            <td class="govuk-table__cell">John Smith</td>

            <td class="govuk-table__cell">Blue</td>

            <td class="govuk-table__cell">Complete</td>

            <td class="govuk-table__cell">25 Jan 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">12323212</a></th>

            <td class="govuk-table__cell">Warren Sutton</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">25 Jan 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">45678765</a></th>

            <td class="govuk-table__cell">Alan Jones</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">12345678</a></th>

            <td class="govuk-table__cell">Jennifer Langley</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">89009800</a></th>

            <td class="govuk-table__cell">Susan Francis</td>

            <td class="govuk-table__cell">Red</td>

            <td class="govuk-table__cell">Incomplete</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">45456765</a></th>

            <td class="govuk-table__cell">John Smith</td>

            <td class="govuk-table__cell">Red</td>

            <td class="govuk-table__cell">Incomplete</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">88675411</a></th>

            <td class="govuk-table__cell">Margaret Blake</td>

            <td class="govuk-table__cell">Red</td>

            <td class="govuk-table__cell">Incomplete</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">44455453</a></th>

            <td class="govuk-table__cell">John Smith</td>

            <td class="govuk-table__cell">Blue</td>

            <td class="govuk-table__cell">Complete</td>

            <td class="govuk-table__cell">25 Jan 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">12323212</a></th>

            <td class="govuk-table__cell">Warren Sutton</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">25 Jan 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">45678765</a></th>

            <td class="govuk-table__cell">Alan Jones</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

          <tr class="govuk-table__row">

            <th scope="row" class="govuk-table__header"><a href="#" class="govuk-link">12345678</a></th>

            <td class="govuk-table__cell">Jennifer Langley</td>

            <td class="govuk-table__cell">Yellow</td>

            <td class="govuk-table__cell">In progress</td>

            <td class="govuk-table__cell">9 May 2018</td>

          </tr>

        </tbody>
      </table>

    </div>
  </div>


{%- from "govuk/components/checkboxes/macro.njk" import govukCheckboxes -%}
{%- from "govuk/components/input/macro.njk" import govukInput -%}
{%- from "govuk/components/table/macro.njk" import govukTable -%}
{%- from "moj/components/filter/macro.njk" import mojFilter -%}
{%- from "moj/components/button-menu/macro.njk" import mojButtonMenu -%}

{% set filterOptionsHtml %}

  {{ govukInput({
    id: 'keywords',
    name: 'keywords',
    label: {
      text: 'Keywords',
      classes: 'govuk-label--m'
    }
  }) }}

  {{ govukCheckboxes({
    idPrefix: 'type',
    name: 'type',
    classes: "govuk-checkboxes--small",
    fieldset: {
      legend: {
        text: 'Colour',
        classes: 'govuk-fieldset__legend--m'
      }
    },
    items: [
      {
        value: '1',
        text: 'Blue (18)',
        checked: true
      },
      {
        value: '2',
        text: 'Yellow (5)',
        checked: true
      },
      {
        value: '3',
        text: 'Red (2)'
      }
    ]
  }) }}

  {{ govukCheckboxes({
    idPrefix: 'status',
    name: 'status',
    classes: "govuk-checkboxes--small",
    fieldset: {
      legend: {
        text: 'Status',
        classes: 'govuk-fieldset__legend--m'
      }
    },
    items: [
      {
        value: '1',
        text: 'Complete (5)',
        checked: true
      },
      {
        value: '2',
        text: 'Incomplete (3)'
      },
      {
        value: '3',
        text: 'In progress (13)'
      }
    ]
  }) }}

{% endset %}


<div class="moj-filter-layout">

  <div class="moj-filter-layout__filter">

    {{ mojFilter({
      heading: {
      text: 'Filter'
      },
      selectedFilters: {

      heading: {
        text: 'Selected filters'
      },

      clearLink: {
        text: 'Clear filters'
      },

      categories: [
        {
          heading: {
            text: 'Colour'
          },
          items: [{
            href: '#',
            text: 'Blue'
          }, {
            href: '#',
            text: 'Yellow'
          }]
        },
        {
          heading: {
            text: 'Status'
          },
          items: [{
            href: '#',
            text: 'Complete'
          }]
        }
      ]
    },
      optionsHtml: filterOptionsHtml
    }) }}

  </div>

  <div class="moj-filter-layout__content">

  <div class="moj-action-bar">

    <div class="moj-action-bar__filter"></div>

    {{ mojButtonMenu({
      items: [{
        text: 'Action 1',
        classes: 'govuk-button--secondary'
      }, {
        text: 'Action 2',
        classes: 'govuk-button--secondary'
      }]
    }) }}

  </div>

  <div class="moj-scrollable-pane">
    {{ govukTable({
      firstCellIsHeader: true,
      head: [
        {text: 'Reference'},
        {text: 'Person'},
        {text: 'Colour'},
        {text: 'Status'},
        {text: 'Date of last event'}
      ],
      rows: [
        [
          {html: '<a href="#" class="govuk-link">44455453</a>'},
          {html: 'John Smith'},
          {text: 'Blue'},
          {html: 'Complete'},
          {text: '25 Jan 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">12323212</a>'},
          {html: 'Warren Sutton'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '25 Jan 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">45678765</a>'},
          {html: 'Alan Jones'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">12345678</a>'},
          {html: 'Jennifer Langley'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">89009800</a>'},
          {html: 'Susan Francis'},
          {text: 'Red'},
          {html: 'Incomplete'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">44455453</a>'},
          {html: 'John Smith'},
          {text: 'Blue'},
          {html: 'Complete'},
          {text: '25 Jan 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">12323212</a>'},
          {html: 'Warren Sutton'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '25 Jan 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">45678765</a>'},
          {html: 'Alan Jones'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">12345678</a>'},
          {html: 'Jennifer Langley'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">89009800</a>'},
          {html: 'Susan Francis'},
          {text: 'Red'},
          {html: 'Incomplete'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">45456765</a>'},
          {html: 'John Smith'},
          {text: 'Red'},
          {html: 'Incomplete'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">88675411</a>'},
          {html: 'Margaret Blake'},
          {text: 'Red'},
          {html: 'Incomplete'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">44455453</a>'},
          {html: 'John Smith'},
          {text: 'Blue'},
          {html: 'Complete'},
          {text: '25 Jan 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">12323212</a>'},
          {html: 'Warren Sutton'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '25 Jan 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">45678765</a>'},
          {html: 'Alan Jones'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '9 May 2018'}
        ],
        [
          {html: '<a href="#" class="govuk-link">12345678</a>'},
          {html: 'Jennifer Langley'},
          {text: 'Yellow'},
          {html: 'In progress'},
          {text: '9 May 2018'}
        ]
      ]
    }) }}
  </div>
</div>

new MOJFrontend.FilterToggleButton({
  bigModeMediaQuery: "(min-width: 48.063em)",
  startHidden: true,
  toggleButton: {
    container: document.querySelector(".moj-action-bar__filter"),
    showText: "Show filter",
    hideText: "Hide filter",
    classes: "govuk-button--secondary",
  },
  closeButton: {
    container: document.querySelector(".moj-filter__header-action"),
    text: "Close",
  },
  filter: {
    container: document.querySelector(".moj-filter"),
  },
});

When to use

Use this pattern to help users refine a set of items either in a list or a set of search results. This pattern should be used instead of advanced search.

When not to use

Don't use this pattern if there aren't many items to filter.

How to use

The list should first appear unfiltered. After selecting one or more filters, the user submits the form which filters the list.

By default filters shouldn't persist across sessions or navigation. Where there is a clear user need, you can specify which filters should persist and for how long.

The filters can be any form control, including date inputs, checkboxes, free text and radio buttons. Use the appropriate form control for the type of attribute being filtered on.

Filters can be used in combination with search. In this case, the flow should be:

  1. Type a search term and submit the search form
  2. See a search results page with filters
  3. Users can then filter the search results page further or search again starting from (1)