--- title: "BigInt Filter" framework: javascript version: "36.1.0" --- # BigInt Filter BigInt Filters allow you to filter `bigint` data without precision loss. #### BigInt Filter ```ts import { BigIntFilterModule, ClientSideRowModelModule, ColDef, GridApi, GridOptions, ModuleRegistry, TextEditorModule, createGrid, enableDevValidations, } from "ag-grid-community"; import { getData } from "./data"; // Enable extended validations only for development if (process.env.NODE_ENV !== "production") { enableDevValidations(); } ModuleRegistry.registerModules([ ClientSideRowModelModule, TextEditorModule, BigIntFilterModule, ]); const columnDefs: ColDef[] = [ { field: "ledgerId", headerName: "Ledger ID (BigInt)", cellDataType: "bigint", filter: true, minWidth: 190, }, { field: "balance", headerName: "Balance (BigInt)", cellDataType: "bigint", filter: "agBigIntColumnFilter", minWidth: 190, }, { field: "account", minWidth: 150 }, ]; let gridApi: GridApi; const gridOptions: GridOptions = { columnDefs, defaultColDef: { flex: 1, minWidth: 140, editable: true, }, rowData: getData(), }; const gridDiv = document.querySelector("#myGrid")!; gridApi = createGrid(gridDiv, gridOptions); ``` [Live example: BigInt Filter](https://www.ag-grid.com/examples/filter-bigint/bigint-filter/typescript) ## Enabling BigInt Filters The BigInt Filter is the default filter used for columns with `cellDataType: 'bigint'` when the [Set Filter is Disabled by Default](https://www.ag-grid.com/javascript-data-grid/filter-set/#suppress-set-filter-by-default). It can also be configured explicitly as shown below: ```js const gridOptions = { columnDefs: [ { field: 'totalBigInt', cellDataType: 'bigint', // BigInt Filter is used by default in Community version for bigInt columns filter: true, }, { field: 'ledgerId', // Explicitly configure column to use the BigInt Filter filter: 'agBigIntColumnFilter', }, ], // other grid options ... } ``` ## BigInt Filter Parameters BigInt Filters are configured through the `filterParams` attribute of the column definition (`IBigIntFilterParams` interface): | Property | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `allowedCharPattern` | `string` | | | When specified, the input field will be of type `text`, and this will be used as a regex of all the characters that are allowed to be typed. This will be compared against any typed character and prevent the character from appearing in the input if it does not match. | | `bigintFormatter` | `Function` | | | Typically used alongside `allowedCharPattern`, this provides a custom formatter to convert the bigint value in the filter model into a string to be used in the filter input. This is the inverse of the `bigintParser`. | | `bigintParser` | `Function` | | | Typically used alongside `allowedCharPattern`, this provides a custom parser to convert the value entered in the filter inputs into a bigint that can be used for comparisons. | | `buttons` | `FilterAction[]` | | | Specifies the buttons to be shown in the filter, in the order they should be displayed in. The options are: `'apply'`: If the Apply button is present, the filter is only applied after the user hits the Apply button. `'clear'`: The Clear button will clear the (form) details of the filter without removing any active filters on the column. `'reset'`: The Reset button will clear the details of the filter and any active filters on that column. `'cancel'`: The Cancel button will discard any changes that have been made to the filter in the UI, restoring the applied model. | | `closeOnApply` | `boolean` | | `false` | If the Apply button is present, the filter popup will be closed immediately when the Apply or Reset button is clicked if this is set to `true`. | | `debounceMs` | `number` | | | Overrides the default debounce time in milliseconds for the filter. Defaults are: `TextFilter` and `NumberFilter`: 500ms. (These filters have text field inputs, so a short delay before the input is formatted and the filtering applied is usually appropriate). `DateFilter` and `SetFilter`: 0ms | | `defaultJoinOperator` | `JoinOperator` | | | By default, the two conditions are combined using `AND`. You can change this default by setting this property. Options: `AND`, `OR` | | `defaultOption` | `string` | | | The default filter option to be selected. | | `filterOptions` | `(IFilterOptionDef \| ISimpleFilterModelType)[]` | | | Array of filter options to present to the user. | | `filterPlaceholder` | `FilterPlaceholderFunction \| string` | | | Placeholder text for the filter textbox. | | `inRangeInclusive` | `boolean` | | | If `true`, the `'inRange'` filter option will include values equal to the start and end of the range. | | `includeBlanksInEquals` | `boolean` | | | If `true`, blank (`null` or `undefined`) values will pass the `'equals'` filter option. | | `includeBlanksInGreaterThan` | `boolean` | | | If `true`, blank (`null` or `undefined`) values will pass the `'greaterThan'` and `'greaterThanOrEqual'` filter options. | | `includeBlanksInLessThan` | `boolean` | | | If `true`, blank (`null` or `undefined`) values will pass the `'lessThan'` and `'lessThanOrEqual'` filter options. | | `includeBlanksInNotEqual` | `boolean` | | | If `true`, blank (`null` or `undefined`) values will pass the `'notEqual'` filter option. | | `includeBlanksInRange` | `boolean` | | | If `true`, blank (`null` or `undefined`) values will pass the `'inRange'` filter option. | | `maxNumConditions` | `number` | | `2` | Maximum number of conditions allowed in the filter. | | `numAlwaysVisibleConditions` | `number` | | `1` | By default only one condition is shown, and additional conditions are made visible when the previous conditions are entered (up to `maxNumConditions`). To have more conditions shown by default, set this to the number required. Conditions will be disabled until the previous conditions have been entered. Note that this cannot be greater than `maxNumConditions` - anything larger will be ignored. | | `readOnly` | `boolean` | | `false` | If set to `true`, disables controls in the filter to mutate its state. Normally this would be used in conjunction with the Filter API. | ## Input Parsing and Validation The BigInt Filter accepts decimal integer syntax only: - `500` and `500n` are both accepted and parse to `500n`. - Hex, binary, decimals and scientific notation are rejected. - Invalid input is handled via standard validation and does not crash the grid. ## Custom Parsing To accept other formats, such as hexadecimal, provide a `bigintParser` that converts the entered text to a `bigint` (return `null` for values it cannot parse). Pair it with `allowedCharPattern` so the extra characters can be typed into the filter input. The parsed value is what gets applied to filtering, and the same parser is used by the [Advanced Filter](https://www.ag-grid.com/javascript-data-grid/filter-advanced/) for `bigint` operands. The filter model always stores the parsed value as a canonical decimal string, so provide a `bigintFormatter` — the inverse of the parser — to display stored values back in your own format. It is used by the [Floating Filter](https://www.ag-grid.com/javascript-data-grid/floating-filters/) and by the [Advanced Filter](https://www.ag-grid.com/javascript-data-grid/filter-advanced/) when displaying an operand, which means an entered value is echoed back in the formatter's format rather than exactly as typed. ```js const gridOptions = { columnDefs: [ { field: 'ledgerId', cellDataType: 'bigint', filter: 'agBigIntColumnFilter', filterParams: { allowedCharPattern: '[\\dxXa-fA-F]', bigintParser: (text) => { if (text == null || text.trim() === '') { return null; } try { return BigInt(text); } catch { // incomplete or invalid input (e.g. '0x') while typing return null; } }, }, }, ], // other grid options ... } ``` ## BigInt Filter Model The Filter Model describes the current state of the applied BigInt Filter: | Property | Type | Required | Default | Description | | --- | --- | --- | --- | --- | | `filterType` | `'bigint'` | | | Filter type is always `'bigint'` | | `filter` | `string \| null` | | | The bigint value(s) associated with the filter. Custom filters can have no values (hence both are optional). Range filter has two values (from and to), where `filter` acts as a `from` value. | | `filterTo` | `string \| null` | | | Range filter `to` value. | | `type` | `ISimpleFilterModelType \| null` | | | One of the filter options, e.g. `'equals'` | ## BigInt Filter Options The BigInt Filter presents the same list of [Filter Options](https://www.ag-grid.com/javascript-data-grid/filter-conditions/#filter-options) as the Number Filter: | Option Name | Option Key | Included by Default | | --- | --- | --- | | Equals | `equals` | Yes | | Does not equal | `notEqual` | Yes | | Greater than | `greaterThan` | Yes | | Greater than or equal to | `greaterThanOrEqual` | Yes | | Less than | `lessThan` | Yes | | Less than or equal to | `lessThanOrEqual` | Yes | | Between | `inRange` | Yes | | Blank | `blank` | Yes | | Not blank | `notBlank` | Yes | | Choose one | `empty` | No | The default option for the BigInt Filter is `equals`. ## Applying the BigInt Filter Applying the BigInt Filter is described in more detail in the following sections: - [Apply, Clear, Reset and Cancel Buttons](https://www.ag-grid.com/javascript-data-grid/filter-applying/#apply-clear-reset-and-cancel-buttons) - [Applying the UI Model](https://www.ag-grid.com/javascript-data-grid/filter-applying/#applying-the-ui-model)