Filter
Use when
Use expandable inline filters when users need up to four simple filter controls for lists that appear within containers, such as boxes, on pages or modals. Simple filters include checkboxes and HTML select inputs.
Filter controls are hidden by default and accessed through a Filter button, so they are especially useful for controls that users don't need frequently or that don't have significant impact. If users need more filters or more complex filtering, use a dedicated list view with a filter bar instead, and allow users to navigate to the dedicated list from the container to complete their filtering tasks.
For more details about filtering lists, see the filtering lists guidelines.
Don't use when
Don't use expandable inline filters when users only need one or two simple filter controls that can fit above the lists. Use persistent inline filters instead. Persistent inline filters are especially useful for controls that users will need frequently or that have significant impact.
Don't use expandable inline filters for full-page lists when the main, or only, task for users is to narrow a collection of items or manipulate a pre-filtered collection. Use a filter bar instead to make filters always available and directly selectable.
| Collapsed |  |
| Expanded |  |
| Filter on (expanded) |  |
Filter buttons appear in the toolbar above lists.
Components
Guidelines
- NPM package
@skyux/listsView in NPM | View in GitHub None found.- Install with NPM
npm install --save-exact @skyux/listsNone found.
import { SkyFilterModule } from '@skyux/lists';
Selector: sky-filter-inline
Specifies a wrapper for the inline filters.
Selector: sky-filter-inline-item
Specifies an inline filter.
Selector: sky-filter-summary
Specifies a wrapper for the filters that were applied.
Selector: sky-filter-summary-item
Specifies a filter that was applied.
Inputs
dismissible: boolean
Whether the filter summary item has a close button.
Outputs
dismiss: EventEmitter<void>
Fires when the summary item close button is selected.
itemClick: EventEmitter<void>
Fires when the summary item is selected.
Selector: sky-filter-button
Inputs
active: boolean | undefined
Whether to highlight the filter button to indicate that filters were applied.
We recommend setting this property to true when no indication of filtering is visible
to users. For example, set it to true if you do not display the filter summary.
Default: false
ariaControls: string | undefined
The ID to identify the element that contains
the filtering options that the filter button exposes.
To support accessibility rules for disclosures,
this property is necessary to set the aria-controls attribute when using inline filters.
For more information about the aria-controls attribute, see the WAI-ARIA definition.
ariaExpanded: boolean | undefined
Whether the filtering options are exposed.
To support accessibility rules for disclosures,
this property is necessary to set the aria-expanded attribute when using inline filters.
For more information about the aria-expanded attribute, see the WAI-ARIA definition.
Default: false
ariaLabel: string | undefined
The ARIA label for the filter button. This sets the
filter button's aria-label attribute to provide a text equivalent for screen readers
to support accessibility.
Use a context-sensitive label, such as "Filter constituents." Context is especially important when multiple filter buttons are in close proximity.
In toolbars, filter buttons use the listDescriptor to provide context, and the ARIA label defaults to "Filter <listDescriptor>."
For more information about the aria-label attribute, see the WAI-ARIA definition.
disabled: boolean | undefined
Whether to disable the filter button.
Default: false
filterButtonId: string
The ID for the filter button.
showButtonText: boolean | undefined
Whether to display a "Filter" label beside the icon on the filter button.
Default: false
Outputs
filterButtonClick: EventEmitter<void>
Fires when the filter button is selected.
SKY UX test harnesses are built upon Angular CDK component harnesses. For more information see the Angular CDK component harness documentation.
import { SkyFilterButtonHarness } from '@skyux/lists/testing';
Harness for interacting with a filter button component in tests.
Methods
clickFilterButton(): Promise<void>
Clicks the filter button.
Returns
Promise<void>
getAriaControls(): Promise<null | string>
Gets the filter button's aria-controls attribute.
Returns
Promise<null | string>
getAriaExpanded(): Promise<boolean>
Gets the filter button's aria-expanded attribute.
Returns
Promise<boolean>
getAriaLabel(): Promise<null | string>
Gets the filter button's aria-label.
Returns
Promise<null | string>
getButtonId(): Promise<null | string>
Gets the filter button's id.
Returns
Promise<null | string>
getButtonText(): Promise<string>
Gets the text that appears on the filter button.
Returns
Promise<string>
isActive(): Promise<boolean>
Whether the filter button is active.
Returns
Promise<boolean>
isDisabled(): Promise<boolean>
Whether the filter button is disabled.
Returns
Promise<boolean>
SkyFilterButtonHarness.with(filters: SkyFilterButtonHarnessFilters): HarnessPredicate<SkyFilterButtonHarness>
Gets a HarnessPredicate that can be used to search for a
SkyFilterButtonHarness that meets certain criteria.
Parameters
filters: SkyFilterButtonHarnessFilters
Returns
HarnessPredicate<SkyFilterButtonHarness>
A set of criteria that can be used to filter a list of SkyFilterButtonHarness instances.
interface SkyFilterButtonHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
import { SkyFilterInlineHarness } from '@skyux/lists/testing';
Harness to interact with a filter inline component in tests.
Methods
getItem(filter: SkyFilterInlineItemHarnessFilters): Promise<SkyFilterInlineItemHarness>
Gets a harness for a specific toolbar item that meets certain criteria.
Parameters
filter: SkyFilterInlineItemHarnessFilters
Returns
Promise<SkyFilterInlineItemHarness>
getItems(filters?: SkyFilterInlineItemHarnessFilters): Promise<SkyFilterInlineItemHarness[]>
Gets an array of all toolbar items.
Parameters
filters?: SkyFilterInlineItemHarnessFilters
Returns
Promise<SkyFilterInlineItemHarness[]>
SkyFilterInlineHarness.with(filters: SkyFilterInlineHarnessFilters): HarnessPredicate<SkyFilterInlineHarness>
Gets a HarnessPredicate that can be used to search for a
SkyFilterInlineHarness that meets certain criteria.
Parameters
filters: SkyFilterInlineHarnessFilters
Returns
HarnessPredicate<SkyFilterInlineHarness>
A set of criteria that can be used to filter a list of SkyFilterInlineHarness instances.
interface SkyFilterInlineHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
import { SkyFilterInlineItemHarness } from '@skyux/lists/testing';
Harness to interact with a filter inline item component in tests.
Methods
queryHarness(query: HarnessQuery<T>): Promise<T>
Returns a child harness or throws an error if not found.
Parameters
query: HarnessQuery<T>
Returns
Promise<T>
queryHarnesses(harness: HarnessQuery<T>): Promise<T[]>
Returns child harnesses.
Parameters
harness: HarnessQuery<T>
Returns
Promise<T[]>
queryHarnessOrNull(query: HarnessQuery<T>): Promise<null | T>
Returns a child harness or null if not found.
Parameters
query: HarnessQuery<T>
Returns
Promise<null | T>
querySelector(selector: string): Promise<TestElement>
Returns a child test element or throws an error if not found.
Parameters
selector: string
Returns
Promise<TestElement>
querySelectorAll(selector: string): Promise<TestElement[]>
Returns child test elements.
Parameters
selector: string
Returns
Promise<TestElement[]>
querySelectorOrNull(selector: string): Promise<null | TestElement>
Returns a child test element or null if not found.
Parameters
selector: string
Returns
Promise<null | TestElement>
SkyFilterInlineItemHarness.with(filters: SkyFilterInlineItemHarnessFilters): HarnessPredicate<SkyFilterInlineItemHarness>
Gets a HarnessPredicate that can be used to search for a
SkyFilterInlineItemHarness that meets certain criteria.
Parameters
filters: SkyFilterInlineItemHarnessFilters
Returns
HarnessPredicate<SkyFilterInlineItemHarness>
A set of criteria that can be used to filter a list of SkyFilterInlineItemHarness instances.
interface SkyFilterInlineItemHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
import { SkyFilterSummaryHarness } from '@skyux/lists/testing';
Harness to interact with a filter summary component in tests.
Methods
getItem(filter: SkyFilterSummaryItemHarnessFilters): Promise<SkyFilterSummaryItemHarness>
Gets a harness for a specific toolbar item that meets certain criteria.
Parameters
filter: SkyFilterSummaryItemHarnessFilters
Returns
Promise<SkyFilterSummaryItemHarness>
getItems(filters?: SkyFilterSummaryItemHarnessFilters): Promise<SkyFilterSummaryItemHarness[]>
Gets an array of all toolbar items.
Parameters
filters?: SkyFilterSummaryItemHarnessFilters
Returns
Promise<SkyFilterSummaryItemHarness[]>
SkyFilterSummaryHarness.with(filters: SkyFilterSummaryHarnessFilters): HarnessPredicate<SkyFilterSummaryHarness>
Gets a HarnessPredicate that can be used to search for a
SkyFilterSummaryHarness that meets certain criteria.
Parameters
filters: SkyFilterSummaryHarnessFilters
Returns
HarnessPredicate<SkyFilterSummaryHarness>
A set of criteria that can be used to filter a list of SkyFilterSummaryHarness instances.
interface SkyFilterSummaryHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
import { SkyFilterSummaryItemHarness } from '@skyux/lists/testing';
Harness to interact with a filter summary item component in tests.
Methods
clickItem(): Promise<void>
Clicks the filter summary item.
Returns
Promise<void>
dismiss(): Promise<void>
Dismisses the filter summary item.
Returns
Promise<void>
isDismissible(): Promise<boolean>
Whether the filter summary item is dismissible.
Returns
Promise<boolean>
SkyFilterSummaryItemHarness.with(filters: SkyFilterSummaryItemHarnessFilters): HarnessPredicate<SkyFilterSummaryItemHarness>
Gets a HarnessPredicate that can be used to search for a
SkyFilterSummaryItemHarness that meets certain criteria.
Parameters
filters: SkyFilterSummaryItemHarnessFilters
Returns
HarnessPredicate<SkyFilterSummaryItemHarness>
A set of criteria that can be used to filter a list of SkyFilterSummaryItemHarness instances.
interface SkyFilterSummaryItemHarnessFilters {
dataSkyId?: string | RegExp;
}Properties
dataSkyId?: string | RegExp
Only find instances whose data-sky-id attribute matches the given value.
Loading...