Table of Contents generated with DocToc
-
@nice-digital/nds-filters
Filter components for the NICE Design System
Install Node, and then:
npm i @nice-digital/nds-filters --saveImport the FilterSummary, FilterPanel, FilterGroup, FilterOption, and FilterByInput components from the package and use within JSX:
import React from "react";
import {
FilterSummary,
FilterPanel,
FilterGroup,
FilterOption,
FilterByInput
} from "@nice-digital/nds-filters";
<FilterSummary sorting={sorting} activeFilters={activeFilters}>
Showing results 1 to 10 of 1209
</FilterSummary>
// A filter panel can contain a filter group with filter options to select, and/or a filter by input
<FilterPanel heading="A filter panel">
<FilterGroup heading="Type">
<FilterOption isSelected={true} onChange={onChanged}>
Guidance
</FilterOption>
<FilterOption isSelected={false} onChange={onChanged}>
Advice
</FilterOption>
<FilterOption isSelected={false} onChange={onChanged}>
NICE Pathways
</FilterOption>
</FilterGroup>
<FilterByInput
label="Filter by guidance ID"
name="GID-filter"
/>
</FilterPanel>Note: The React component automatically imports the SCSS, so there's no need to import the SCSS directly yourself.
- Type:
SortingType(required)
Ways to sort the returned results.
Each SortingType item contains an onSelected property - this is a callback function that will
run when that option is selected. If the user isn't running JS then a button will be displayed instead,
submitting the form with the selected option's value.
type SortingType = {
label: string;
value: string;
active?: boolean | undefined;
onSelected?: React.EventHandler<any>;
};const sorting = [
{ label: "Item 1", value: "item-1", onSelected: () => { console.log("Callback 1"); } },
{ label: "Item 2", value: "item-2", onSelected: () => { console.log("Callback 2"); } },
{
label: "Item 3 (active)",
value: "item-3",
onSelected: () => { console.log("Callback 3"); },
active: true
},
];
<FilterSummary sorting={sorting} activeFilters={activeFilters}>
Showing results 1 to 10 of 1209
</FilterSummary>- Type:
FilterType(required)
The filters that are being applied to the data, creates a tag that can be clicked to eg remove that filter.
If an onClick function is passed, the elementType will default to a button. If no onClick or elementType is passed, it will default to an anchor and you should pass it a destination for the href. If you use a custom elementType, you should also pass the method and destination for the element to use, eg "to" for Gatsby.
type FilterType = {
label: string;
destination?: string;
onClick?: React.MouseEventHandler;
elementType?: React.ElementType;
method?: string;
className?: string;
};const activeFilters = [
{
label: "My filter",
elementType: Link,
to: "somewhere",
},
{
label: "Another filter",
onClick: onChanged
}
];
<FilterSummary sorting={sorting} activeFilters={activeFilters}>
Showing results 1 to 10 of 1209
</FilterSummary>- Type:
ReactNode
The heading text of the filter summary. Will be a <h2> unless the headingLevel prop is provided to change the level.
- Type:
string
Any additional classes that you would like applied to the <FilterSummary /> component
<FilterSummary sorting={sorting} activeFilters={activeFilters} className="mb--f">
Showing results 1 to 10 of 1209
</FilterSummary>- Type:
2 | 3 | 4 | 5 - Default:
2
The heading level for the filter summary. This defaults to 2, but you may need to change it depending on the rest of the page structure.
When you initialize a variable with an object, TypeScript assumes that the properties of that object might change values later, so the heading level provided here would be inferred to be a number as it could be reassigned before use. This means TypeScript will consider the code to have an error if you pass the fallback prop to filter panel with headingLevel: 3. Instead you need to add a type assertion like so: headingLevel: 3 as 3.
<FilterSummary sorting={sorting} activeFilters={activeFilters} headingLevel={3 as 3}>
Showing results 1 to 10 of 1209
</FilterSummary>Any additional props are spread on to the first div element, useful for accessibility or data attributes.
- Type:
ReactNode
The body text of the filter panel
- Type:
string
Any additional classes that you would like applied to the <FilterPanel /> component
<FilterPanel heading="A filter panel" className="mb--f" />- Type:
string(required)
The heading for the filter panel
<FilterPanel heading="A filter panel" />- Type:
fallback?: {
action?: string;
method?: "GET" | "POST";
};The <FilterPanel /> is a form, which will submit via the form action (GET request by default), if js is not available. If js is available and an action is supplied, it will override the default behaviour.
When you initialize a variable with an object, TypeScript assumes that the properties of that object might change values later, so the method here would be inferred to be a string as it could be reassigned before use. This means TypeScript will consider the code to have an error if you pass the fallback prop to filter panel with method: "POST". Instead you need to add a type assertion like so: method: "POST" as "POST".
<FilterPanel
heading="A filter panel"
fallback={{
action: "/submit-form",
method: "POST" as "POST"
}}> />- Type:
React.MouseEventHandler
This gets used when js is available instead of the fallback above.
- Type:
2 | 3 | 4 | 5 - Default:
2
The heading level for the panel heading. This defaults to 2, but you may need to change it depending on the rest of the page structure. This heading level cascades to the <FilterGroup /> and <FilterByInput /> components, which have their headings set to the headingLevel you provide here + 1.
As above, when you initialize a variable with an object, TypeScript assumes that the properties of that object might change values later, so the heading level provided here would be inferred to be a number as it could be reassigned before use. This means TypeScript will consider the code to have an error if you pass the fallback prop to filter panel with headingLevel: 3. Instead you need to add a type assertion like so: headingLevel: 3 as 3.
<FilterPanel
heading="A filter panel"
headingLevel={3 as 3}> />Any additional props are spread on to the form element, useful for accessibility or data attributes.
- Type:
string(required)
The heading for the filter group
<FilterGroup heading="Type" />- Type:
string
The id for the filter panel
<FilterGroup heading="Type" id="ProductType"/>- Type:
number
How many of the options in the group are currently selected ie how many filters are applied.
<FilterGroup heading="Type" selectedCount={99}/>- Type:
boolean - Default:
false
The filter group can be collapsed to hide the filter options.
<FilterGroup heading="Type" collapseByDefault={true}/>- Type:
ReactNode
One or more <FilterOption \> components.
- Type:
string
Any additional classes that you would like applied to the <FilterGroup /> component
<FilterGroup heading="Type" className="mb--f" />Any additional props are spread on to the first div element, useful for accessibility or data attributes.
- Type:
string
Passed from the parent <FilterGroup />, will be the id or slufigied heading of the parent <FilterGroup />.
- Type:
string
Passed from the parent <FilterGroup />, will be the heading of the parent <FilterGroup />.
- Type:
boolean(required)
If the option is selected by default
<FilterOption isSelected={true} onChanged={onChanged}>
Guidance
</FilterOption>- Type:
string(required)
The label text of the filter option. The value defaults to this if no value is provided
<FilterOption isSelected={true} onChanged={onChanged}>
Guidance
</FilterOption>- Type:
string
The value of the input
<FilterOption isSelected={true} onChange={onChanged} value="guidance">
Guidance
</FilterOption>- Type:
function(required)
What happens when the checkbox is selected
<FilterOption isSelected={true} onChanged={onChanged}>
Guidance
</FilterOption>Any additional props are spread on to the label element, useful for accessibility or data attributes.
- Type:
string(required)
The label for the input
<FilterByInput
label="Filter by guidance ID"
name="GID-filter"
/>- Type:
string(required)
The name for the input
<FilterByInput
label="Filter by guidance ID"
name="GID-filter"
/>- Type:
string - Default: "Filter"
Replace the label for the button
<FilterByInput
label="Filter by guidance ID"
name="GID-filter"
buttonLabel="Filter results"
/>- Type:
string
Any additional classes that you would like applied to the <FilterByInput /> component
<FilterByInput
label="Filter by guidance ID"
name="GID-filter"
className="mb--f"
/>- Type:
boolean - Default:
false
The filter by input panel can be collapsed to hide the input and button.
<FilterByInput
label="Filter by guidance ID"
name="GID-filter"
collapseByDefault={true}
/>- Type: "color" | "date" | "datetime-local" | "email" | "file" | "hidden" | "image" | "month" | "number" | "range" | "password" | "search" | "tel" | "text" | "time" | "url" | "week";
- Default: "text""
The type of input for the filter
<FilterByInput
label="Filter by guidance ID"
name="GID-filter"
type="number"
/>- Type:
object
Any props you would like to spread on to the <Input /> component, examples given below. See the documentation for nds-input for more options.
<FilterByInput
label="Filter by guidance ID"
name="GID-filter"
inputProps={{
hint: "enter your search term here",
error: true,
errorMessage: "NOOOO",
"data-tracking": "message"
}}
/>Any additional props are spread on to the first div element, useful for accessibility or data attributes.
If you're not using React, then import the SCSS directly into your application by:
@forward '@nice-digital/nds-filters/scss/filters';If you're not using React, then include the SCSS as above and use the HTML:
<form title="Filter" action="/submit-form" method="POST">
<div class="filter-panel undefined">
<h2 class="filter-panel__heading">
<button aria-expanded="true" aria-controls="filter-panel-body">A filter panel</button>
</h2>
<div id="filter-panel-body" class="filter-panel__body" aria-hidden="false">
// For a filter group
<div class="filter-group">
<h3 class="filter-group__heading">
<button type="button" aria-expanded="true" aria-controls="group-ProductType">
<span id="group-heading-ProductType">Type</span>
</button>
</h3>
<fieldset id="group-ProductType" aria-hidden="false" class="filter-group__options">
<legend>Type</legend>
<label for="filter_ProductType_guidance" class="filter-option">
<input id="filter_ProductType_guidance" type="checkbox" name="ProductType" title="Type - Guidance" value="Guidance" checked="">
<span class="filter-option__text">Guidance</span>
</label>
<label for="filter_ProductType_advice" class="filter-option">
<input id="filter_ProductType_advice" type="checkbox" name="ProductType" title="Type - Advice" value="Advice">
<span class="filter-option__text">Advice</span>
</label>
<label for="filter_ProductType_nice-pathways" class="filter-option">
<input id="filter_ProductType_nice-pathways" type="checkbox" name="ProductType" title="Type - NICE Pathways" value="NICE Pathways">
<span class="filter-option__text">NICE Pathways</span>
</label>
</fieldset>
</div>
// For a filter by input
<div class="inputFilterBox">
<h3 class="inputFilterBox__heading">
<button type="button" aria-expanded="false" aria-controls="inputFilter-filter">Filter by GID</button>
</h3>
<div id="inputFilter-filter" aria-hidden="true" class="inputFilterBox__controls">
<div class="input">
<label class="input__label" for="filter">Filter by GID</label>
<input name="filter" class="input__input" id="filter" type="text" value="">
</div>
<button type="submit" class="btn ml--0 mb--0">Filter</button>
</div>
</div>
</div>
</div>
</form>