External filtering allows custom filtering logic to be mixed with the grid's inbuilt filtering.
This form of filtering is only compatible with the Client-Side Row Model, see Row Models for more details.
import { createApp, defineComponent, ref, shallowRef } from "vue";
import type {
ColDef,
GridApi,
GridReadyEvent,
IDateFilterParams,
IRowNode,
} from "ag-grid-community";
import {
ClientSideRowModelModule,
DateFilterModule,
ExternalFilterModule,
ModuleRegistry,
NumberFilterModule,
enableDevValidations,
} from "ag-grid-community";
import {
ColumnMenuModule,
ColumnsToolPanelModule,
ContextMenuModule,
SetFilterModule,
} from "ag-grid-enterprise";
import { AgGridVue } from "ag-grid-vue3";
import type { IOlympicData } from "./interfaces";
import "./styles.css";
if (process.env.NODE_ENV !== "production") {
// Enable extended validations only for development
enableDevValidations();
}
ModuleRegistry.registerModules([
ExternalFilterModule,
ClientSideRowModelModule,
ColumnsToolPanelModule,
ColumnMenuModule,
ContextMenuModule,
SetFilterModule,
NumberFilterModule,
DateFilterModule,
]);
const asDate = (dateAsString: string): Date => {
const splitFields = dateAsString.split("/");
return new Date(
Number.parseInt(splitFields[2]),
Number.parseInt(splitFields[1]) - 1,
Number.parseInt(splitFields[0]),
);
};
const dateFilterParams: IDateFilterParams = {
comparator: (filterLocalDateAtMidnight: Date, cellValue: string) => {
const cellDate = asDate(cellValue);
if (filterLocalDateAtMidnight.getTime() === cellDate.getTime()) {
return 0;
}
if (cellDate < filterLocalDateAtMidnight) {
return -1;
}
if (cellDate > filterLocalDateAtMidnight) {
return 1;
}
return 0;
},
};
const VueExample = defineComponent({
template: `
<div class="test-container">
<div class="test-header">
<label>
<input type="radio" name="filter" id="everyone" checked v-on:change="onAgeTypeChanged('everyone')">
Everyone
</label>
<label>
<input type="radio" name="filter" id="below25" v-on:change="onAgeTypeChanged('below25')">
Below 25
</label>
<label>
<input type="radio" name="filter" id="between25and50" v-on:change="onAgeTypeChanged('between25and50')">
Between 25 and 50
</label>
<label>
<input type="radio" name="filter" id="above50" v-on:change="onAgeTypeChanged('above50')">
Above 50
</label>
<label>
<input type="radio" name="filter" id="dateAfter2008" v-on:change="onAgeTypeChanged('dateAfter2008')">
After 01/01/2008
</label>
</div>
<ag-grid-vue
style="width: 100%; height: 100%;"
:columnDefs="columnDefs"
:defaultColDef="defaultColDef"
:rowData="rowData"
:isExternalFilterPresent="isExternalFilterPresent"
:doesExternalFilterPass="doesExternalFilterPass"
@grid-ready="onGridReady"></ag-grid-vue>
</div>
`,
components: {
"ag-grid-vue": AgGridVue,
},
setup() {
// A ref, so the callbacks below can be created once in setup() and keep their reference.
const ageType = ref("everyone");
const rowData = ref<IOlympicData[] | null>(null);
const gridApi = shallowRef<GridApi<IOlympicData> | null>(null);
const columnDefs = ref<ColDef<IOlympicData>[]>([
{ field: "athlete", minWidth: 180 },
{ field: "age", filter: "agNumberColumnFilter" },
{ field: "country" },
{ field: "year" },
{
field: "date",
filter: "agDateColumnFilter",
filterParams: dateFilterParams,
},
{ field: "total", filter: "agNumberColumnFilter" },
]);
const defaultColDef = ref<ColDef>({
flex: 1,
minWidth: 120,
filter: true,
});
const isExternalFilterPresent = (): boolean => ageType.value !== "everyone";
const doesExternalFilterPass = (node: IRowNode<IOlympicData>): boolean => {
if (node.data) {
switch (ageType.value) {
case "below25":
return node.data.age < 25;
case "between25and50":
return node.data.age >= 25 && node.data.age <= 50;
case "above50":
return node.data.age > 50;
case "dateAfter2008":
return asDate(node.data.date) > new Date(2008, 0, 1);
default:
return true;
}
}
return true;
};
const onGridReady = (params: GridReadyEvent<IOlympicData>) => {
gridApi.value = params.api;
fetch("https://www.ag-grid.com/example-assets/olympic-winners.json")
.then((response) => response.json())
.then((data: IOlympicData[]) => (rowData.value = data));
};
const onAgeTypeChanged = (newValue: string) => {
ageType.value = newValue;
gridApi.value!.onFilterChanged();
};
return {
columnDefs,
defaultColDef,
rowData,
isExternalFilterPresent,
doesExternalFilterPass,
onGridReady,
onAgeTypeChanged,
};
},
});
createApp(VueExample).mount("#app");
.test-container {
height: 100%;
display: flex;
flex-direction: column;
}
.test-header {
font-family: Verdana, Geneva, Tahoma, sans-serif;
font-size: 13px;
margin-bottom: 10px;
display: flex;
justify-content: space-around;
border: 1px solid grey;
padding: 10px;
border-radius: 5px;
}
Implementing External Filtering Copy Link
The example above shows external filters in action. Two methods on gridOptions are required to be implemented: isExternalFilterPresent and doesExternalFilterPass.
Grid calls this method to know if an external filter is present.
Called exactly once every time the grid senses a filter change.
Should return true if external filtering is active, otherwise false.
If true, doesExternalFilterPass is called while filtering, otherwise it is not called.
Supplying a new function reference re-runs external filtering. |
Called once for each row node in the grid.
Should return true if external filter passes, otherwise false.
If false, the node is excluded from the final set.
Only runs if isExternalFilterPresent returns true.
Supplying a new function reference re-runs external filtering. |
Re-running the External Filter Copy Link
The filter state is held outside the grid, so the grid has to be told when that state has changed. Pick one of the following approaches:
- Calling onFilterChanged - the callback references are kept stable and the filter is re-run only when the API is called.
- Supplying New Callbacks - a new callback reference is handed to the grid and the filter is re-run automatically.
Calling onFilterChanged Copy Link
After the filter state has changed call api.onFilterChanged() to ask the grid to run filtering again.
Informs the grid that a filter has changed. This is typically called after a filter change through one of the filter APIs.
source: The source of the filter change event. If not specified defaults to 'api'. |
// Filter state updated now re-run filtering
api.onFilterChanged();Ensure the callbacks have stable references to avoid triggering filtering excessively.
Framework bindings make it easy to hand over a new reference by accident, which re-runs the filter outside of the application's control. A callback defined in setup and returned unchanged keeps its reference; one recreated on every render does not.
Supplying New Callbacks Copy Link
isExternalFilterPresent and doesExternalFilterPass are reactive grid properties, so replacing either one with a new function re-runs filtering automatically.
// reassigning the ref hands the grid a new reference, and filtering re-runs
doesExternalFilterPass.value = (node) => node.data.age > minAge.value;The example on this page takes the first path: the callbacks are stable, and each change to the filter state calls api.onFilterChanged().