Docs

Loop filter

Let visitors filter and sort a loop grid by category, search or other fields.

On this page

The Loop Filter widget adds category buttons, a dropdown, checkboxes, a search box or a sort menu above a Loop Grid or a Posts widget. When a visitor picks a filter, the grid updates in place without reloading the page, and the address bar changes so the filtered view can be shared, bookmarked and reached with the browser's Back button.

The Journal page on the live site with All posts, Design notes, Materials and Renovation filter buttons above three post cards
Category buttons above the Journal grid.

Add a filter to a grid

  1. Add the grid first

    Place a Loop Grid (or a Posts widget) on the page and set its query to Custom query. See Loop grid & carousel.

  2. Add the Loop Filter

    From Insert, drag Loop Filter above the grid. It is in the Site & theme group.

  3. Choose what it filters by

    In Content → Filter, pick Filter by: Category, tag or taxonomy, Custom field, Search or Sort order, and set the options below.

  4. Check it on the live site

    Filters work on the live page and in the preview, not on the editor canvas.

To offer several ways to filter, add several Loop Filter widgets, for example category buttons and a search box. They all work together on the same grid: choosing a category keeps the search text, and the other way round. Each filter narrows the others; several choices within one filter widen it (any of them).

Filter settings

The Loop Filter settings: Grid anchor ID, Filter by, Taxonomy, Display and the options for category buttons
Content → Filter of a Loop Filter.
Filter
SettingWhat it does
Grid anchor IDWhich grid to filter. Leave it empty when the page has a single grid. With several grids, give the grid an Anchor ID in Behaviour → Anchor & classes and type the same ID here.
Filter byCategory, tag or taxonomy, Custom field, Search or Sort order.
TaxonomyWhich terms to list: Categories, Tags or a public custom taxonomy.
DisplayButtons, Dropdown or Checkboxes.
Allow several at onceButtons only: visitors can turn on several terms. Checkboxes always allow several.
Show “All”Adds a first button or option that clears the filter. Not used with checkboxes.
“All” labelText of that option ("All" by default), for example "All posts".
Show countsShows the number of posts next to each term.
Hide empty termsLeaves out terms without posts. On by default.
Top-level terms onlyLeaves out child categories.
Field keyCustom field only: the key of the custom field the posts have, for example location. See Filter by a custom field.
Show posts whose fieldCustom field only: Is the chosen value, Is at least the chosen number or Is at most the chosen number.
OptionsCustom field only: one choice per line, the value or Label|value. Empty lists the values the posts have, A–Z.
PlaceholderSearch only: the hint in the empty search box ("Search…" by default).
Sort optionsSort only: which orders the menu offers: Newest first, Oldest first, Title A–Z, Title Z–A, Recently updated, Most commented, Custom order. The menu always starts with Default order.
LabelText shown before the filter, also read by screen readers.
Label positionBeside the filter or Above the filter: the label on its own line, with a dropdown or search box as wide as the widget. Use it for a row of filters, such as a job board's sector, location and salary. Shown when there is a Label.

The Design tab sets the alignment, gap, typography and colors of the buttons and fields, including the Active text and Active background of the selected button, plus radius and padding.

Filter by a custom field

Posts can carry facts of their own in custom fields: the location and contract of a job, the number of bedrooms of a home, the price of a product. A Loop Filter set to Custom field filters the grid by one of them, so a job board can offer Location, Contract and Salary side by side.

  1. Give the posts the field, with the same key on each, for example location with the value Manchester.
  2. Add a Loop Filter above the grid, set Filter by to Custom field and type the Field key: location.
  3. Leave Options empty to list the values the posts have (Leeds, London, Manchester), or type them in your order. Remote (UK)|remote shows Remote (UK) and matches posts whose field is remote.

For numbers, store a plain number in the field (45000, not £45,000), set Show posts whose field to Is at least the chosen number (or at most) and list the thresholds as options: £40,000+|40000, £60,000+|60000. A visitor who picks £60,000+ sees the posts whose field is 60000 or more; posts without the field are left out while a threshold is chosen.

Fields whose key starts with an underscore are private in WordPress: they cannot filter a grid, and Uncoder never shows them.

How visitors use it

  • Buttons are links: clicking one shows only that category. With Allow several at once, each click adds or removes a term.
  • Dropdown, Checkboxes and Sort order update the grid as soon as the choice changes.
  • Search updates the grid shortly after the visitor stops typing, or when they press Enter.
  • Filtering always goes back to the first page of the grid.

Every filter works without JavaScript too: the page then reloads with the filter applied.

Note

The filter works with every query source. On an archive (a grid set to Current query (archives)), it narrows the archive's own posts: for example a tag filter on a category page shows the posts of that category with that tag.