PHPackages swishdigital/faceted-navigation - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Search & Filtering](/categories/search) 4. / 5. swishdigital/faceted-navigation ActiveCraft-plugin[Search & Filtering](/categories/search) swishdigital/faceted-navigation =============================== Provides faceted navigation of entries, using categories, which allows site users to narrow the list of entries they see by applying multiple filters (think Amazon or eBay left sidebar). 5.0.0(2y ago)152.4k↑100%2MITPHPCI failing Since Apr 21Pushed 2y ago1 watchersCompare [ Source](https://github.com/helloswish/craft-faceted-navigation)[ Packagist](https://packagist.org/packages/swishdigital/faceted-navigation)[ RSS](/packages/swishdigital-faceted-navigation/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (8)Dependencies (1)Versions (10)Used By (0) Faceted Navigation plugin for Craft CMS 3.x/4.x/5.x =================================================== [](#faceted-navigation-plugin-for-craft-cms-3x4x5x) Provides faceted navigation of entries, using categories, which allows site users to narrow the list of entries they see by applying multiple facets (think Amazon or eBay left sidebar). Adapted with permission from its original author, the incomparable Iain Urquhart () Requirements ------------ [](#requirements) This plugin requires Craft CMS 3.0.0-beta.23 or later, Craft CMS 4.0.0-alpha.1 or later, or Craft CMS 5.x or later. Installation ------------ [](#installation) To install the plugin, follow these instructions. ### Craft Plugin Store [](#craft-plugin-store) Locate Faceted Navigation in the plugin store and click install ### Manual Installation [](#manual-installation) 1. Open your terminal and go to your Craft project: ``` cd /path/to/project ``` 2. Then tell Composer to load the plugin: ``` composer require helloswish/craft-faceted-navigation ``` 3. In the Control Panel, go to Settings → Plugins and click the “Install” button for Faceted Navigation. ### Settings [](#settings) Version 1.1.1 introduced a single setting in the Control Panel, which allows you to choose if users can select multiple filters per filter group. By default, users can *not* select multiple filters per filter group. Faceted Navigation Overview --------------------------- [](#faceted-navigation-overview) This plugin provides the functionality necessary to implement faceted navigation on a site built with Craft CMS 3 or 4. To read more about faceted navigation, check out this [2010 A List Apart article](https://alistapart.com/article/design-patterns-faceted-navigation/). You can see examples of this plugin in action, and try it out, on the following sites: - [The Lotus Collection](https://ktaylor-lotus.com/inventory) - [Stemple Creek Ranch](https://stemplecreek.com/shop) The plugin provides the following functionality: - Ability to use a single category group, or multiple category groups for filtering - Ability to add as many categories as the user likes to filter the list of entries - Add and Remove links for each category to add or remove the category from the list of categories being provided to the entries query to filter on - A list of currently added categories, with remove links, that can be shown independently of the full categories list - Ability to provide either AND or OR filtering with multiple facets (only one or the other for all facets applied, not a combination of AND and OR) *Note: this plugin will only work with category groups that use 1 level of categories.* Screenshots ----------- [](#screenshots) [![Example faceted navigation interface](resources/img/1.jpg)](resources/img/1.jpg)[![List of categories with add and remove links](resources/img/2.jpg)](resources/img/2.jpg)[![List of currently added categories with remove links](resources/img/3.jpg)](resources/img/3.jpg) Implementing Faceted Navigation ------------------------------- [](#implementing-faceted-navigation) I'll be using The Lotus Collection (linked above) implmentation to demonstrate how to setup the plugin. ### 1. Add Route [](#1-add-route) Add this route to your config/routes.php file: `'inventory/' => ['template' => 'inventory/index']` *(this example assumes the faceted navigation will be located at and the template that is shown for that url is located in your Craft templates folder at inventory/index)* This route will ensure that all requests that begin with *inventory* and include any number of facets in the url will be directed to the correct template. All other implementation is done in your template code. ### 2. Setup Channel, Categories, Fields, and Entries [](#2-setup-channel-categories-fields-and-entries) *Note: this plugin will only work with category groups that use 1 level of categories.* Create a channel for your entries in the Craft Control Panel. For this example, we'll call it *Inventory*. Create one or more category groups in the Craft Control Panel. For The Lotus Collection, I created 3 groups. The handles are `productType`, `productOrigin`, and `textileType`. [![Category groups](resources/img/4.gif)](resources/img/4.gif) Add your categories to each group. Create category fields, one for each category group, and assign them to your inventory channel. [![Category fields](resources/img/5.jpg)](resources/img/5.jpg) Add your entries, and assign all the appropriate categories to them. [![Categories assigned to an entry](resources/img/6.jpg)](resources/img/6.jpg) ### Template Code [](#template-code) Calling `craft.facetedNavigation.buildFacets` allows you to render your navigation sets and output current filters, as well as build a parameter for your main craft.entries call when outputting your entries. **Basic Tag Set** At or near the top of your inventory/index template, paste in the basic set tag, along with an array of your category group handles. We'll also setup the `relationParam` variable, which can be AND or OR, depending on how you want your facets to filter your entries query. Finally, we'll setup a `params` array to feed into our entries query later. ``` {% set navItems = craft.facetedNavigation.buildFacets(['productType', 'productOrigin', 'textileType']) %} {% set relationParam = ['and'] %} {% set params = { section: 'inventory' } %} ``` You should add other craft.entries parameters to the params array here, as we'll be appending to it later. **Output Category Facets** In order to apply categories as facets on your entry query, you need to first display the categories in your template. Those categories must be linked so that when clicked, they are each added to the group of categories being used to filter the entries query. When a category is currently added, a remove link can be displayed. ``` {% for categoryGroup in navItems.categoryGroups %} {{ categoryGroup.name }} {% for category in attribute( navItems.categories, categoryGroup.handle ) %} {{ category.title}} {% if category.active %} Remove {% endif %} {% endfor %} {% endfor %} ``` A few notes about the above code: - This will loop through all category groups that you provided to the basic tag set (above). Then within each group, it loops through and displays the categories. - `category.active` is a boolean that is `true` if the category is currently applied. - `category.url.add` creates the link to add the category. Use `{{ url('inventory'~category.url.add) }}` to create the link. - `category.url.remove` creates the link to remove the category. Use `{{ url('inventory'~category.url.remove) }}` to create the link. **Output Currently Added Categories** You may want to show a list of currently applied facets. This is also a good place to build our `relatedTo` variable, which will become a parameter for the craft.entries query. ``` {% if navItems.activeCategories|length %} Viewing items in these categories: {% for category in navItems.activeCategories %} {% set relationParam = relationParam|merge([{ targetElement:category }]) %} {{ category.title }} Remove {% endfor %} {% endif %} ``` A few notes about the above code: - `{% if navItems.activeCategories|length %}` tests to see if there are currently added categories. If not, this entire block of code is skipped. - `{% set relationParam = relationParam|merge([{ targetElement:category }]) %}` adds another parameter to the `relationParam` array that we set anove in the basic tag set. For each added category, another parameter is added to that array. - We're again using `{{ url('inventory'~category.url.remove) }}` to create the remove link. **Run the Entries Query** We've now collected all the parameters we need to feed into craft.entries: ``` {% if relationParam|length > 1 %} {% set params = params|merge({relatedTo: relationParam}) %} {% endif %} {% set inventory = craft.entries(params) %} {% for product in inventory.all() %} ... {% endfor %} ``` A note about the above code: - We're only merging the `relationParam` array into the `params` array (set at the top in the basic tag set) if there are any added categories. Otherwise the craft.entries query only gets the parameters set initially on that array, which, in this example, is the section handle `inventory `. **Full Code Example** Here is the full code I used on The Lotus Collection site. It includes surrounding HTML and other Craft functionality: --- *Brought to you by [Swish Digital](https://swishdigital.co)* ### Health Score 37 — LowBetter than 82% of packages Maintenance31 Infrequent updates — may be unmaintained Popularity28 Limited adoption so far Community9 Small or concentrated contributor base Maturity65 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~229 days Recently: every ~376 days Total 9 Last Release 743d ago Major Versions 1.1.4 → 2.0.0-alpha2022-05-31 2.0.0 → 5.0.02024-04-26 ### Community Maintainers ![](https://www.gravatar.com/avatar/aa032da94102be5908fc58ea10624fdd78ea68570e91f511250052562bdfcfa7?d=identicon)[chadcrowell](/maintainers/chadcrowell) --- Top Contributors [![chadcrowell](https://avatars.githubusercontent.com/u/48151?v=4)](https://github.com/chadcrowell "chadcrowell (10 commits)") --- Tags filtercmsfilteringfilterscategoriesCraftcraftcmscraft-pluginnavigationcategorysidebarfaceted navigation ### Embed Badge ![Health badge](/badges/swishdigital-faceted-navigation/health.svg) ``` [![Health](https://phpackages.com/badges/swishdigital-faceted-navigation/health.svg)](https://phpackages.com/packages/swishdigital-faceted-navigation) ``` ### Alternatives [verbb/navigation Create navigation menus for your site. 90683.7k17](/packages/verbb-navigation)[studioespresso/craft-scout Craft Scout provides a simple solution for adding full-text search to your entries. Scout will automatically keep your search indexes in sync with your entries. 80136.8k](/packages/studioespresso-craft-scout)[trendyminds/algolia Easily pull search results from Algolia into your Craft CMS website 1332.2k](/packages/trendyminds-algolia)[la-haute-societe/craft-elasticsearch Bring the power of Elasticsearch to your Craft CMS projects. 1712.4k](/packages/la-haute-societe-craft-elasticsearch)[swixpop/locate Harness the power of the Google Autocomplete API inside Craft. Adds an autocomplete search box to Craft entries. 154.8k](/packages/swixpop-locate)[fork/craft-elastica A plugin to connect to Elasticsearch and persist elements via hooks 101.8k](/packages/fork-craft-elastica) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)