--- product: "AG Studio" title: "Filter Widgets" description: "Add list, button and date filter controls to an AG Studio report page: which field each needs, single or multiple selection, and date filter types." framework: react version: "3.1.0" related: - title: "Using the Catalogue" url: "https://www.ag-grid.com/studio/analysts/widget-catalogue/" - title: "Table Widgets" url: "https://www.ag-grid.com/studio/analysts/table-widgets/" - title: "Value Widgets" url: "https://www.ag-grid.com/studio/analysts/value-widgets/" - title: "Static Content" url: "https://www.ag-grid.com/studio/analysts/static-content-widgets/" llms: "https://www.ag-grid.com/studio/llms.txt" --- # Filter Widgets Filter Widgets give report viewers controls on the page itself for narrowing down the data, so they don't need to open the [Filters](https://www.ag-grid.com/studio/analysts/filters-panel/) panel. Each selection shows as a read-only card in the Filters Panel, as described in [Filter Widget Cards](https://www.ag-grid.com/studio/analysts/filters-panel/#filter-widget-cards). **Button Filter** shows clickable toggle buttons for quick single or multi-value filtering. Use it when the list of values is short enough to display as buttons. **List Filter** shows a scrollable list for selecting one or more values from many options. Use it when there are too many values to show as buttons. **Date Filter** shows date boxes, with a slider for the range types, for filtering by date range or specific dates. The example below shows all three Filter Widgets alongside a KPI Widget showing total revenue from a year of orders. The Button Filter lists the four sales regions, the List Filter lists the products and the Date Filter covers the order dates. Selecting a value in any Filter updates the KPI, because the KPI reflects the combined selection of all of them. #### Filter ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { "button-filter": { type: "button-filter", dataMapping: { value: [{ id: "orders.region" }], }, format: { title: { enabled: true, text: "Button Filter", }, }, }, "list-filter": { type: "list-filter", dataMapping: { value: [{ id: "orders.product" }], }, format: { title: { enabled: true, text: "List Filter", }, }, }, "date-filter": { type: "date-filter", dataMapping: { value: [{ id: "orders.order_date" }], }, format: { title: { enabled: true, text: "Date Filter", }, }, }, value: { type: "value", dataMapping: { value: [{ id: "orders.revenue", aggregation: "sum" }], }, format: { style: { label: { enabled: true, }, }, subtitle: { enabled: true, text: "For the regions, products and dates selected", }, }, }, }, widgetLayout: { "button-filter": { xTrack: 0, yTrack: 0, xSpan: 8, ySpan: 16, }, "list-filter": { xTrack: 8, yTrack: 0, xSpan: 8, ySpan: 16, }, "date-filter": { xTrack: 16, yTrack: 0, xSpan: 8, ySpan: 16, }, value: { xTrack: 0, yTrack: 16, xSpan: 24, ySpan: 8, }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Filter](https://www.ag-grid.com/studio/examples/filter-widgets/filter/typescript/) ## Setup Each Filter Widget takes one field, and filters the report by it. | Widget | Slot | Required | Accepts | What it does | | --- | --- | --- | --- | --- | | Button Filter, List Filter | Value | Yes | One category | Shows one button or list item for each value of the field. | | Date Filter | Value | Yes | One date field | Filters by the dates chosen in the date boxes or on the slider. | ## Format Filter Widgets have these settings of their own on the Format tab, beside the title and appearance settings every Widget has. Your developer can change the defaults shown. | Setting | Where | Default | What it does | | --- | --- | --- | --- | | Selection Type | Button Filter or List Filter section | Multiple | Lets viewers select several values, or one at a time. See [Selection Type](https://www.ag-grid.com/studio/analysts/filter-widgets/#selection-type). | | Alignment | Button Filter section | Center | Aligns the text in each button. | | Border | Button Filter section | On | Draws a border around each button. **Width**, **Corner Radius** and **Color** change the border. | | Active Style | Button Filter section | Theme colours | Sets the text, background and border colours of a selected button. | | Dimensions | Button Filter section | Min Width 100, Height 50 | Sets the narrowest width and the height of each button, in pixels. Buttons widen to fill each row. | | Filter Type | Date Filter section | Between | Chooses how dates are picked. See [Date Filter Types](https://www.ag-grid.com/studio/analysts/filter-widgets/#date-filter-types). | The Button Filter and List Filter sections also set the font and colour of each item. The example below shows a selection of Button Filter settings, each changed in its own Widget, beside a Button Filter with its defaults. #### Button Filter Format ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { "default-buttons": { type: "button-filter", dataMapping: { value: [{ id: "orders.region" }], }, format: { title: { enabled: true, text: "Default Buttons", }, subtitle: { enabled: true, text: "No Button Filter settings changed", }, }, }, "alignment-left": { type: "button-filter", dataMapping: { value: [{ id: "orders.region" }], }, format: { title: { enabled: true, text: "Alignment: Left", }, subtitle: { enabled: true, text: "Button Filter > Alignment Left", }, style: { defaultItem: { textAlign: "left", }, }, }, }, "border-off": { type: "button-filter", dataMapping: { value: [{ id: "orders.region" }], }, format: { title: { enabled: true, text: "Border Off", }, subtitle: { enabled: true, text: "Button Filter > Border off", }, style: { defaultItem: { borderEnabled: false, }, }, }, }, dimensions: { type: "button-filter", dataMapping: { value: [{ id: "orders.region" }], }, format: { title: { enabled: true, text: "Dimensions", }, subtitle: { enabled: true, text: "Dimensions > Min Width 200, Height 36", }, style: { dimensions: { minWidth: 200, height: 36, }, }, }, }, }, widgetLayout: { "default-buttons": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 18 }, "alignment-left": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 18 }, "border-off": { xTrack: 0, yTrack: 18, xSpan: 12, ySpan: 18 }, dimensions: { xTrack: 12, yTrack: 18, xSpan: 12, ySpan: 18 }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Button Filter Format](https://www.ag-grid.com/studio/examples/filter-widgets/button-filter-format/typescript/) ### Selection Type With **Multiple**, viewers can select as many values as they like. With **Single**, selecting a value replaces the one selected before. In a List Filter, each value has a checkbox beside it for Multiple, or a radio button for Single. Under Single, the first item, **Select All**, clears the filter. The example below shows a List Filter of products with each Selection Type. #### Selection Type ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { multiple: { type: "list-filter", dataMapping: { value: [{ id: "orders.product" }], }, format: { title: { enabled: true, text: "Multiple Selection", }, subtitle: { enabled: true, text: "List Filter > Selection Type Multiple", }, }, }, single: { type: "list-filter", dataMapping: { value: [{ id: "orders.product" }], }, format: { title: { enabled: true, text: "Single Selection", }, subtitle: { enabled: true, text: "List Filter > Selection Type Single", }, style: { selection: { type: "single", }, }, }, }, }, widgetLayout: { multiple: { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 16 }, single: { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 16 }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Selection Type](https://www.ag-grid.com/studio/examples/filter-widgets/filter-selection/typescript/) ### Date Filter Types The Filter Type sets how a Date Filter chooses its dates: - **Between** keeps the dates from a start date to an end date. - **On** keeps one date. - **On or After** and **On or Before** keep the dates from, or up to, one date. - **Relative** keeps a period counted from today, such as the last 30 days or this month. For the Between, On or After and On or Before filter types, a slider below the date boxes runs from the field's earliest date to its latest. Drag a handle to choose a date. The date box updates as you drag, and the filter applies when you let go. To clear a date, drag the start handle to the far left or the end handle to the far right. You can also move a focused handle with the arrow keys, Page Up and Page Down, and Home and End. The example below shows a Date Filter of order dates with each Filter Type. #### Date Filter Types ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { between: { type: "date-filter", dataMapping: { value: [{ id: "orders.order_date" }], }, format: { title: { enabled: true, text: "Between", }, subtitle: { enabled: true, text: "Date Filter > Filter Type Between", }, }, }, on: { type: "date-filter", dataMapping: { value: [{ id: "orders.order_date" }], }, format: { title: { enabled: true, text: "On", }, subtitle: { enabled: true, text: "Date Filter > Filter Type On", }, style: { filterType: "on", }, }, }, "on-or-after": { type: "date-filter", dataMapping: { value: [{ id: "orders.order_date" }], }, format: { title: { enabled: true, text: "On or After", }, subtitle: { enabled: true, text: "Date Filter > Filter Type On or After", }, style: { filterType: "onOrAfter", }, }, }, "on-or-before": { type: "date-filter", dataMapping: { value: [{ id: "orders.order_date" }], }, format: { title: { enabled: true, text: "On or Before", }, subtitle: { enabled: true, text: "Date Filter > Filter Type On or Before", }, style: { filterType: "onOrBefore", }, }, }, relative: { type: "date-filter", dataMapping: { value: [{ id: "orders.order_date" }], }, format: { title: { enabled: true, text: "Relative", }, subtitle: { enabled: true, text: "Date Filter > Filter Type Relative", }, style: { filterType: "relative", }, }, }, }, widgetLayout: { between: { xTrack: 0, yTrack: 0, xSpan: 8, ySpan: 16 }, on: { xTrack: 8, yTrack: 0, xSpan: 8, ySpan: 16 }, "on-or-after": { xTrack: 16, yTrack: 0, xSpan: 8, ySpan: 16 }, "on-or-before": { xTrack: 0, yTrack: 16, xSpan: 8, ySpan: 16 }, relative: { xTrack: 8, yTrack: 16, xSpan: 8, ySpan: 16 }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Date Filter Types](https://www.ag-grid.com/studio/examples/filter-widgets/date-filter-types/typescript/)