Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

docs(filter): Updates images for v6. #4338

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

docs(filter): Updates images for v6. #4338

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
98fa51f
docs(filter): Updates images for v6.
edonehoo Oct 24, 2024
dc39338
More images and adds alt text.
edonehoo Oct 30, 2024
ad10cf7
Merge branch 'main' into iss4324
edonehoo Oct 31, 2024
620edf3
Content edits for clarity
edonehoo Nov 4, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion packages/documentation-site/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@
"screenshots": "pf-docs-framework screenshots"
},
"dependencies": {
"@patternfly/documentation-framework": "6.0.0-alpha.118",
"@patternfly/documentation-framework": "6.0.0-alpha.120",
"@patternfly/react-catalog-view-extension": "6.0.0-prerelease.1",
"@patternfly/react-console": "6.0.0-prerelease.2",
"@patternfly/react-docs": "7.0.0-prerelease.32",
Expand Down
124 changes: 96 additions & 28 deletions ...patternfly-docs/content/design-guidelines/usage-and-behavior/filters/filters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,8 @@ related: [
]
---

import "../../components/components.css"

**Filters** allow users to narrow down content from data in tables, data lists or card views, among many others.

PatternFly provides a number of components that can be used in a variety of combinations to create a custom filtering experience. These elements may be used in a toolbar or on their own.
Expand All @@ -35,7 +37,9 @@ There are various ways to allow users to filter down content. Filtering methods
### Text entry filters
A text entry filter provides the user with an input field to type in values that filter the view, whether or not their input is an exact match. The text entry filter uses the [search input](/components/search-input) component which can be used with or without a button.

<img src="./img/text-input.png" alt="text input filters" width="880"/>
<div class="ws-docs-content-img">
![](./img/text-entry-filters.svg)
</div>

1. **Basic search input:** Filters automatically, as soon as the user starts typing.
2. **Search input with button:** Filters on enter, or click of arrow button.
Expand All @@ -55,12 +59,24 @@ Text entry filters support [filter labels](#filter-label), but do not support [t

**Filter labels** are supported for text entry filters, but in general, we recommend not showing a label to avoid redundancy, except for cases when text entry filters are used inside of [attribute-value filters](#attribute-value-filter). Since you can only search by one value at a time, the value will already be shown in the input field.

<img src="./img/text-input-chips.png" alt="text input labels" width="880"/>
<div class="ws-docs-content-img">
![](./img/search-value.svg)
</div>

### Single select
A single select provides the user with a fixed set of values from which they can only select one value. This filter type uses the [single select component](/components/select/react#single). If the single select filter is the only filter in the toolbar, it should have an “All options” menu item by default as a way to reset the filter (unless a selection must be made at all times). This “All” option will be selected by default, acting as an equivalent of no filter selected.
A single select provides the user with a fixed set of values from which they can only select one value. This filter type uses the [single select component](/components/select/react#single).

If the single select filter is the only filter in the toolbar, it should have an “All options” menu item that's selected by default, acting as an equivalent of no filter selected.

<div class="ws-docs-content-img">
![](./img/single-select-default.svg)
</div>

<img src="./img/single-select.png" alt="single select list filter" width="880"/>
When a different menu item is selected, it should be displayed in the toggle. Selecting "All options" will reset any selected options.

<div class="ws-docs-content-img">
![](./img/single-select-selection-mode.svg)
</div>

#### Behavior
The user is presented with a list of values to choose from. A selected value is indicated with a blue checkmark to the right of the value. When a value is selected, the selection appears in the toggle.
Expand All @@ -74,14 +90,18 @@ Single selects can include [type-aheads](#type-ahead) as an added feature.

**Type-ahead** functionality can be added to single selects, allowing users to input a search inside the toggle, filtering down from the list of menu options shown. This is especially useful for very long lists that would be inconvenient for the user to scroll through. Type-ahead is recommended for lists that are more than 10 items long.

<img src="./img/single-type-ahead.png" alt="type-ahead in a single select" width="564"/>
<div class="ws-docs-content-img">
![](./img/typeahead-input.svg)
</div>

Stand alone single selects in a toolbar do not use badge counts or filter labels since only one selection can be made, and the selection will already be apparent in the toggle.

### Checkbox select
A checkbox select provides the user with a fixed set of values from which they can select multiple values. This filter type uses the [checkbox select component](/components/select/react#checkbox-input).

<img src="./img/checkbox-select.png" alt="checkbox select"/>
<div class="ws-docs-content-img">
![](./img/checkbox-select-menus.svg)
</div>

#### Behavior
The user is presented with a list of values to choose from. From this list, users may select or deselect one or more values at a time, with selections indicated by a blue checkbox preceding the value. The dropdown should remain open as the user makes selections until they click away or manually close it. Selected values will appear as filter labels underneath the filter, allowing the user to see their selections even when the toggle is collapsed.
Expand All @@ -92,29 +112,41 @@ Use a checkbox select for selecting multiple values from a predefined list. Mult
#### Supported features
Checkbox select supported features include [filter labels](#filter-label), and optionally, [badges](#badge-count).

<img src="./img/checkbox-select-add.png" alt="add ons for checkbox select" width="880"/>
<div class="ws-docs-content-img">
![](./img/checkbox-select.svg)
</div>

**Filter labels** are used as a way for users to view all their selections when the menu of selections is collapsed.

**Badges** can be used in the checkbox select toggle to indicate how many selections have been made, although they are not required.

Although **typeahead** is not supported for checkbox selects, you can add a search input inside the menu, right above the items the user can select from. This will allow the user to filter down the list of options.

<img src="./img/checkbox-search.png" alt="search in checkbox select" width="475" />
<div class="ws-docs-content-img">
![](./img/typeahead-search.svg)
</div>

## Variations for multiple attributes
There are multiple ways of combining variations for single attribute filters into multiple attribute filters, including [attribute-value filters](#attribute-value-filter), [filter groups](#filter-group), [toggle groups](#toggle-group) and [faceted filters](#faceted-filter).

### Attribute-value filter
The attribute-value filter gives users the ability to specify an attribute-value pair for filtering a data set.

<img src="./img/attribute-filter.png" alt="Attribute filter with basic search" />
<div class="ws-docs-content-img">
![](./img/attribute-a.svg)
</div>

<img src="./img/attribute-filter-single.png" alt="Attribute filter with single select" />
<div class="ws-docs-content-img">
![](./img/attribute-b.svg)
</div>

<img src="./img/attribute-filter-checkbox.png" alt="Attribute filter with checkbox" />
<div class="ws-docs-content-img">
![](./img/attribute-c.svg)
</div>

<img src="./img/attribute-filter-date-picker.png" alt="Attribute filter with date picker" />
<div class="ws-docs-content-img">
![](./img/attribute-d.svg)
</div>

The following elements make up an attribute-value (textbox) filter.
1. **Attribute selector:** A select list that allows the user to select the attribute that they want to filter against.
Expand Down Expand Up @@ -156,10 +188,30 @@ Attribute-value filter features include [filter labels](#filter-label), [badges]
### Filter group
A filter group is a set of filters that appear side by side in a toolbar. This filter type uses the [select list](/components/select) component.

<img src="./img/filter-group-2.png" alt="filter group with multiple selects" />
**Filter group with only single selects**

<div class="ws-docs-content-img">
![](./img/filter-group-single.svg)
</div>

1. When an option is selected, it is reflected in the toggle.
1. The default selection should be “All _attribute-name_” to indicate that no filter has been applied. This option also allows users to clear whatever filter they may have applied.


**Filter group with multiple selection types**

<div class="ws-docs-content-img">
![](./img/filter-group-multiple.svg)
</div>

1. **Filter group with only single select:** Filter group made up of single selects. When an option is selected, it is reflected in the toggle. The default selection should be “All _attribute-name_” to indicate that no filter has been applied. This option also allows users to clear whatever filter they may have applied.
2. **Filter group with multiple selection types:** Filter group with single select, checkbox select, and date picker. When there are no selections, the toggle should contain the attribute name. When selections are made, the behavior will depend on the selection type. For single selects and date pickers, the selection will appear in the toggle. For checkbox selects, the attribute name will remain in the toggle, with the addition of a badge containing the number of filters selected. In all cases, selections should appear as filter labels underneath the filters.
Filter group with single select, checkbox select, and date picker. When there are no selections, the toggle should contain the attribute name.

When selections are made, the behavior will depend on the selection type:
1. **Single select:** The selection will appear in the toggle.
1. **Checkbox selects:** The attribute name will remain in the toggle, with the addition of a badge containing the number of filters selected.
1. **Date pickers:** The selection will appear in the toggle.

In all cases, selections should appear as filter labels underneath the filters.

#### When to use
Use a filter group when you only have a handful of attributes that you want to show. Only use this filter when space allows; otherwise consider using an attribute-value or faceted filter instead.
Expand All @@ -179,7 +231,9 @@ Filter groups support [filter labels](#filter-label), [badges](#badge-count), an
### Toggle group
A toggle group filter allows users to select from a set of predefined different elements to filter something on. This filter uses the [toggle group component](/components/toggle-group).

<img src="./img/toggle-group.png" alt="toggle group" width="541" />
<div class="ws-docs-content-img">
![](./img/toggle-filter.svg)
</div>

#### When to use
Use a toggle group filter when you have few filter options that you want users to filter from, without hiding the options in a select list. A common usage for toggle groups is for filtering a chart view, to include or remove a data point from view.
Expand All @@ -193,12 +247,19 @@ Toggle groups do not use or support filter labels, badges, or type-ahead.
### Faceted filter
Faceted filtering is useful when items can be described by categories according to multiple dimensions or facets. This filter usually uses the [grouped checkbox select list](/components/select#grouped-checkbox-input) component.

<img src="./img/faceted-grouped.png" alt="faceted filter with checkbox" />
<div class="ws-docs-content-img">
![](./img/faceted-filter.svg)
</div>

The following elements can be used in a faceted (checkbox) filter:
1. **Facets:** Different categories containing filter values, such as _Status_ or _Vendor_.
2. **Values:** What users might filter on. Each category is made up of checkbox selects, where each category can have multiple options selected. Never include two selection types within the same faceted filter.
3. **Filter labels:** Records of each selection, shown when the options menu is collapsed.

<div class="ws-docs-content-img">
![](./img/faceted-filter-collapsed.svg)
</div>

1. **Filter labels:** Records of each selection, shown when the options menu is collapsed.

**Note:** Consider adding an “Other” option to attribute lists where items may not fall under any of the specified values.

Expand Down Expand Up @@ -245,7 +306,9 @@ When filters are applied, filter labels may be used to provide feedback to the u

Filter labels may be used to show boolean relationships between different attribute-value pairs. Individual filter labels can be removed by clicking the ‘x’ in each label, and entire filter groups can be removed using the group ‘x’.

<img src="./img/chips.png" alt="label groups" />
<div class="ws-docs-content-img">
![](./img/filter-label.svg)
</div>

Follow these best practices for using filter labels:
* Filters between attribute categories should be combined with a boolean “AND” operator.
Expand All @@ -269,12 +332,15 @@ Badges are used to indicate a count. In filters, badges can be used in the follo
#### Badge in checkbox select
You may opt to use a badge in a checkbox select to indicate to the user how many items they have selected when the toggle is collapsed.

<img src="./img/badge.png" alt="badge" />
<div class="ws-docs-content-img">
![](./img/badge-count.svg)
</svg>
edonehoo marked this conversation as resolved.
Show resolved Hide resolved

### Type-ahead
Adding type-ahead capabilities to your filters is useful when there is a large number of items to select from the filter dropdown. Users can quickly find the value they would like to filter by typing in the field.

<img src="./img/type-ahead-single.png" alt="type ahead example" />
<div class="ws-docs-content-img">
![](./img/typeahead.svg)
</div>

Type-ahead is supported in single selects, faceted filters that can handle one input. Users may scroll through the dropdown list or type in the box to find the desired option.

Expand All @@ -299,23 +365,26 @@ If your filter has limitations, you may present an error state on your filter to

When using error validation in a filter, include a tooltip on hover with an explanation of what went wrong.

<img src="./img/error-table.png" alt="Example of filter validation"/>
![](./img/filter-error.svg)

## Layout considerations
Filters may be included in a [toolbar](/components/toolbar) and are usually left aligned. There may be more than one filter used in a single toolbar, and in some cases, custom filters may make up a full toolbar. Filters may also be used alone outside of a toolbar.

## Mobile considerations
In responsive views, filters may be hidden within the filter icon. On click, the toolbar will expand to reveal the filter. If there are multiple filter elements, they will be collapsed into a single faceted filter. Read more about toolbars in mobile views in [the toolbar design guidelines](/components/toolbar/design-guidelines#the-toolbar-on-mobile).

<img src="./img/mobile.png" alt="mobile view" width="880" />
![](./img/mobile-before.svg)

![](./img/mobile-after.svg)

## Examples
**Filter group in data list toolbar**
<img src="./img/ex-datalist.png" alt="example of filter group in data list" width="880" />

[add img]

**Attribute filter in table toolbar**
<img src="./img/ex-table.png" alt="example of attribute value filter in table " width="880" />

[Add img]

## Content

Expand All @@ -325,5 +394,4 @@ Filter placeholder text in input fields should read “Filter by [attribute name
**Examples:** _Filter by status_, _Filter by vendor_

### Clearing filters
The option to clear all filters will be displayed after the last filter label. It should read “Clear filters” in sentence case. When clicked, it should remove all applied filters and collapse the toolbar back into a single row.

The option to clear all filters will be displayed after the last filter label. It should read “Clear filters” in sentence case. When clicked, it should remove all applied filters and collapse the toolbar back into a single row.
Loading
Loading