Skip to main content

Patterns

Filter

The Filter Component is a list of categories used to get more granular results in a search. With JavaScript enabled, the Filter Component will toggle open or closed using the Toggle JavaScript Utility. All of the same accessible attribute toggling functionality the Toggle Utility provides will apply (aria-controls, aria-expanded, and aria-hidden). The markup for the list can be a navigation <nav> element with hyperlinks or standard unordered list <ul> element with hyperlinks <a> or buttons <buttons> as the filtering element. Hyperlinks would be used for filters that navigate to different pages and buttons would trigger in-page functionality. Below is an example of a filter using a navigation element with hyperlinks.

<div class="c-filter"><button aria-controls="aria-c-programs" aria-expanded="true" class="c-filter__header active" data-js="filter" id="aria-lb-programs" type="button">All Programs</button>
  <nav aria-hidden="false" aria-labelledby="aria-lb-programs" class="c-filter__list active" id="aria-c-programs" role="region"><span class="c-filter__item">All Programs</span><a class="c-filter__item" href="#">Cash &amp; Expenses</a><a class="c-filter__item" href="#">Child Care</a><a class="c-filter__item" href="#">City ID Card</a><a class="c-filter__item" href="#">Education</a><a class="c-filter__item" href="#">Enrichment</a><a class="c-filter__item" href="#">Family Services</a><a class="c-filter__item" href="#">Food</a><a class="c-filter__item" href="#">Health</a><a class="c-filter__item" href="#">Housing</a><a class="c-filter__item" href="#">Special Needs</a><a class="c-filter__item" href="#">Work</a></nav>
</div>

The Multi Filter Component allows for multiple selections and nested filter categories. There are alternate patterns for toggling all checkboxes within a group which include a checkbox on the parent menu toggle or a nested short link within the menu accordian.

<div class="c-filter-multi bg-color-white">
  <ul class="c-filter-multi__list">
    <li class="c-filter-multi__item"><button aria-controls="aria-c-cash-and-expenses" aria-expanded="true" class="c-filter-multi__item-header btn-link active" data-js="filter" id="aria-lb-cash-and-expenses" type="button">Cash &amp; Expenses<span class="c-filter-multi__item-header-toggle"></span></button>
      <div aria-hidden="false" aria-labelledby="aria-lb-cash-and-expenses" class="c-filter-multi__item-group active" id="aria-c-cash-and-expenses" role="region">
        <ul class="c-filter-multi__item-group-list">
          <li class="c-filter-multi__item-group-subitem"><button class="btn-link" type="button">Toggle All</button></li>
          <li class="c-filter-multi__item-group-subitem"><label class="checkbox"><input type="checkbox" value="6871" /><span class="checkbox__label text-font-size-small font-normal">Home Energy Assistance Program (HEAP)</span></label></li>
          <li class="c-filter-multi__item-group-subitem"><label class="checkbox"><input type="checkbox" value="6868" /><span class="checkbox__label text-font-size-small font-normal">Earned Income Tax Credit (EITC)</span></label></li>
        </ul>
      </div>
    </li>
    <li class="c-filter-multi__item">
      <div class="c-filter-multi__item-header"><label class="checkbox"><input type="checkbox" /><span class="checkbox__label">Child Care</span></label><button aria-controls="aria-c-child-care" aria-expanded="true" class="c-filter-multi__item-header-toggle active" data-js="filter" type="button"><span class="sr-only" id="aria-lb-child-care">Child Care</span></button></div>
      <div aria-hidden="false" aria-labelledby="aria-lb-child-care" class="c-filter-multi__item-group active" id="aria-c-child-care" role="region">
        <ul class="c-filter-multi__item-group-list">
          <li class="c-filter-multi__item-group-subitem"><label class="checkbox"><input type="checkbox" value="6866" /><span class="checkbox__label text-font-size-small font-normal">EarlyLearn Child Car</span></label></li>
          <li class="c-filter-multi__item-group-subitem"><label class="checkbox"><input type="checkbox" value="6867" /><span class="checkbox__label text-font-size-small font-normal">EarlyLearn Head Start</span></label></li>
        </ul>
      </div>
    </li>
    <li class="c-filter-multi__item">
      <div class="c-filter-multi__item-header"><label class="checkbox"><input type="checkbox" /><span class="checkbox__label">City ID Card</span></label><button aria-controls="aria-c-city-id-card" aria-expanded="false" class="c-filter-multi__item-header-toggle" data-js="filter" type="button"><span class="sr-only" id="aria-lb-city-id-card">City ID Card</span></button></div>
      <div aria-hidden="true" aria-labelledby="aria-lb-city-id-card" class="c-filter-multi__item-group" id="aria-c-city-id-card" role="region">
        <ul class="c-filter-multi__item-group-list">
          <li class="c-filter-multi__item-group-subitem"><label class="checkbox"><input type="checkbox" value="6871" /><span class="checkbox__label text-font-size-small font-normal">IDNYC</span></label></li>
        </ul>
      </div>
    </li>
  </ul>
</div>

Global Script

The Filter and Filter Multi Components require the Filter JavaScript for toggling functionality and screen reader accessibility. It will work for both the Filter and Filter Multi Components. To use the Filter in the global ACCESS NYC Patterns script use the following code:

<!-- Global Script -->
<script src="dist/scripts/access-nyc.js"></script>

<script>
  var access = new AccessNyc();
  access.filter();
</script>

This function will attach the filter toggling event to the body of the document.

Cherry-picked Module Import

The ES6, CommonJS, and IFFE modules all require importing and object instantiation in your main script:

// ES6
import Filter from 'src/components/filter/filter';

// CommonJS
let Filter = require('dist/components/filter/filter.common');

<!-- IFFE -->
<script src="dist/components/filter/filter.iffe.js"></script>

new Filter();

Polyfills

This script uses the Toggle Utility as a dependency and requires the same polyfills. See the "Toggle Usage" section for more details.

The Vue Filter is a packaged Filter Component for Vue.js applications. It encapsulates markup, accessibility, data-binding, and event emitting for a fully functional component. See Vue Component Usage below for details on data and events that can be passed as properties to the component.

<div id="app-c-filter">
  <c-filter :nav="true" :strings="strings" :terms="termsFilter" @fetch="fetch" @reset="reset"></c-filter>
</div>
<div id="app-c-filter-multi">
  <c-filter-multi :strings="strings" :terms="termsFilterMulti" @fetch="fetch" @reset="reset"></c-filter-multi>
</div>

The Vue Filter and Vue Filter Multi can be imported from the paths below in your main script and added to the Vue instance before your application declaration:

import FilterVue from 'src/components/filter/filter.vue';
import FilterMultiVue from 'src/components/filter/filter-multi.vue';

Vue.component('c-filter', FilterVue);
Vue.component('c-filter-multi', FilterMultiVue);

new Vue();

Below is a guide for using these particular component properties. For basic details of using Vue Components within a Vue application, refer to the Vue.js documentation.

Props

Below is a description of accepted properties and their values.

Prop Type Description
:terms object/array Data for the filter list. A sample set of data can be seen here. The Vue Filter will only accept one terms object from the sample array. The Vue Multi Filter will accept an array of term objects.
:strings object A dictionary containing static strings used in the component. Below is a table containing the available strings.

Strings

Key Default Description
ALL All The prefix before the term name, ex; "All Programs"
TOGGLE_ALL Toggle All Text for the button that toggles all filters within a term group.

Events

The Vue Filter and Vue Filter Multi accepts two event properties that are emitted on click. Passing methods to these props provides hooks for the parent application. You can open the console log of this page to see demonstration logs for each event.

Key Params Description
@fetch event, data Internally this event will set the state of the currently selected filter in a group. The emitter can be used to "fetch" data when the term is clicked. Event is the original click event. Data contains the data bound to the clicked filter.
@reset event, data The emitter can be used to reset the filters data. Event is the original click event. Data contains the data bound to the clicked filter.