Filtering Summary Chart
ZingGrid's built-in filter summary chart provides a visual way to explore and filter data using an interactive summary chart.
First, enable filter summaries by setting the filter attribute to "summary" on your <zing-grid> element.
This adds a filter toggle button to the upper-left corner of the grid, allowing users to show or hide the filter summary row.
The filter summary row contains interactive summary charts that provide a visual overview of the data and can be used to filter records directly.
Chart types
There are two types of filter summary charts: distributive and categorical.
Distributive charts are used by default for numeric and date-based columns. The following supported types are:
- Calendar: a drilldown calendar for date-based columns. The view adapts to the dataset's date range across four views: month, year, 2-3 years, and 4+ years. Filtering is performed by selecting a single or group of nodes, or through the calendar selection overlay to select nodes or provide a date range.
- Histogram: the default for numeric and date-based columns. Each histogram node (bin) represents a range of values. Filtering is performed using a selection range that can be moved or resized to adjust the filter criteria.
Categorical charts are used by default for all other column types. The following chart types are supported:
- Bar: the default for most categorical columns.
- Pie: the default for columns with only two possible values, such as boolean, checkbox, and toggle columns.
- Ring: similar to the pie chart, but in a ring shape.
- Toggle: toggle to switch between two values.
Filtering is performed by selecting one or more nodes. For bar and pie charts, a filter is applied when a node is clicked. Clicking an active node will remove that filter condition.
To specify the summary chart type, use the [filter-summary-chart] attribute.
This can be set at the grid or column level.
The chart type options are:
- bar
- calendar
- default
- histogram
- pie
- ring
- toggle
Bar, pie, and ring charts map each category to an individual node. When a dataset contains too many categories, the nodes can become too narrow to render, resulting in an empty chart. In this case, the chart type is automatically changed to a histogram, which groups categories into nodes to provide a visualization.
Additionally, the following are supported:
- Long labels are truncated
- NaN nodes are yellow
- Boolean false nodes are red
- Color type nodes fill color are set to the color it represents
- Clear button appears when filter is active to clear filter results
<zing-grid filter="all" filter-summary-chart="bar">...</zing-grid>
Node Sort Order
The default node ordering depends on the chart type:
- Bar and Pie: Nodes are sorted by count in descending order.
- Histogram: Nodes are sorted by value for numeric columns and alphabetically for all other supported column types.
However, node order is configurable through the [filter-summary-node-sort] attribute, which accepts:
- alphabetical: alphabetically by their label
- count-asc: count in ascending order
- count-desc: count in descending order
- default: default based on chart and column type
- gradient: in gradient order (only for color column type)
- value: node numeric value (only for numeric column types)
- none: retain original order
Disable multiple node filter
By default, categorical charts allow filtering by multiple nodes.
To disable this feature, set [filter-summary-multi-node] to "disabled".
Filter mode
By default, the filter summary operates in "cumulative" mode. Filters selected from the filter summary are appended to the current filter set, allowing multiple columns to be filtered simultaneously.
To make filter summary selections "exclusive", set [filter-summary-mode] to "exclusive".
In exclusive mode, applying a filter from a column clears any previously applied filter summary filters from other columns, ensuring that only one filter summary selection is active at a time.
Collapse Filter Summary Row
By default, the filter summary is displayed when the grid loads.
To keep the filter summary collapsed on initial load, set [filter-summary-row-collapsed] to true.
Filter by raw values
By default, the filter applies to rendered values.
To filter by raw values instead, set [filter-on] to "raw".
Set Ring Thickness
By default, the ring chart uses a ring thickness of 0.5.
To customize the ring thickness, set [filter-summary-ring-thickness] to a value between 0 and 1.
Lens mode
Depending on the chart type or the amount of nodes, the filter summary chart may be difficult to view. Allow users to enable lens mode to view a larger version of the summary chart to interact or apply filter with.
Enable this feature with [filter-summary-lens].
This can be enabled at the grid- or column-level.
At the column-level, [filter-summary-lens] accepts an additional option, "disabled", to turn off lens mode for that column.
Card Mode Support
Filter summary charts are also supported in card mode.
A filter summary menu button is added to the control bar. Clicking this button opens a filter summary chart in an overlay, similar to lens mode.
Contextmenu to Change Chart
Users can change the filter summary chart type from the context menu.
To enable this feature, add the [context-menu] attribute to <zing-grid>.
When the context menu is opened on a filter summary row (including while in Lens mode), it displays all chart types supported by that column, allowing users to switch between them. Unsupported chart types are disabled.
The standard context menu behavior remains unchanged when the menu is opened from the grid header or body.
For more information about the context menu, see the Context Menu documentation
When changing the chart type, any existing chart selection is preserved if it is compatible with the new chart type. Otherwise, the selection is cleared.
Chart compatibility is grouped as follows:
- Categorical charts: Bar, Pie, Ring, Toggle
- Histogram: Histogram
- Calendar: Calendar
For example, changing between Bar, Pie, Ring, and Toggle preserves the current selection. Changing to or from Histogram or Calendar clears the selection because they are not compatible with the other chart groups.
More filter options
Setting filter to summary only enables interactive filter summary charts.
The filter attribute can also enable inline or menu.
For more information about inline filtering, check out Filtering.
For more information about menu filtering, check out Filtering Advanced Docs.
Or enable all filtering options by setting filter to "all".
External Input
You can use an external input and our API method filterSummaryColumn() (see below) to dynamically apply summary filtering to the grid from an external input.
const zgRef = document.querySelector('zing-grid'); zgRef.filterSummaryColumn('columnIndex', ['columnFilterValue(s)']);
To reset filter, use the resetFilter() method.
This method could also be applied to a specified column.
const zgRef = document.querySelector('zing-grid'); zgRef.resetFilter('fieldIndex'); // Specify column by field index, or reset all columns by leaving blank
The following API methods can dynamically get or set filter on the grid:
getFilter()setFilter()
Related Resources
Here are some extra resources related to this feature to help with creating your grid:
[features: filtering summary chart]