---
title: "Number Filter"
framework: javascript
version: "36.1.0"
---

# Number Filter

Number Filters allow you to filter numeric data.

![Number Filter](https://www.ag-grid.com/_astro/number-filter.CzQ3JNC5.png)

## Enabling Number Filters

#### Number Filter

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  ModuleRegistry,
  NumberFilterModule,
  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, NumberFilterModule]);

const columnDefs: ColDef[] = [
  {
    field: "price",
    filter: true,
  },
  {
    field: "quantity",
    filter: "agNumberColumnFilter",
  },
];

let gridApi: GridApi;

const gridOptions: GridOptions = {
  columnDefs,
  defaultColDef: {
    flex: 1,
    minWidth: 150,
  },
  rowData: getData(),
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);
```

[Live example: Number Filter](https://www.ag-grid.com/examples/filter-number/number-filter/typescript)

The Number Filter is the default filter used in AG Grid Community for columns with number [Cell Data Type](https://www.ag-grid.com/javascript-data-grid/cell-data-types/), but it can also be explicitly configured as shown below:

```js
const gridOptions = {
    columnDefs: [
        {
            field: 'price',
            // Number Filter is used by default in Community version for numeric columns
            filter: true,
            filterParams: {
                // pass in additional parameters to the Number Filter
            },
        },
        {
            field: 'quantity',
            // explicitly configure column to use the Number Filter
            filter: 'agNumberColumnFilter',
            filterParams: {
                // pass in additional parameters to the Number Filter
            },
        },
    ],

    // other grid options ...
}
```

## Number Filter Parameters

Number Filters are configured through the `filterParams` attribute of the column definition (`INumberFilterParams` 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. |
| `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. See [Filter Options](https://www.ag-grid.com/javascript-data-grid/filter-number/#number-filter-options) for more information. |
| `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. |
| `numberFormatter` | `Function` |  |  | Typically used alongside `allowedCharPattern`, this provides a custom formatter to convert the number value in the filter model into a string to be used in the filter input. This is the inverse of the `numberParser`. |
| `numberParser` | `Function` |  |  | Typically used alongside `allowedCharPattern`, this provides a custom parser to convert the value entered in the filter inputs into a number that can be used for comparisons. |
| `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. See [Read-only Filter UI](https://www.ag-grid.com/javascript-data-grid/filter-api/#read-only-filter-ui) for more information. |

## Custom Number Support

The default behaviour of the Number Filter is to use a `number` input, however this has mixed browser support and behaviour. If you want to override the default behaviour, or allow users to type other characters (e.g. currency symbols, commas for thousands, etc.), the Number Filter allows you to control what characters the user is allowed to type. In this case, a `text` input is used with JavaScript controlling what characters the user is allowed (rather than the browser). You can also provide custom logic to parse the provided value into a number to be used in the filtering.

Custom number support is enabled by specifying configuration similar to the following:

```js
const gridOptions = {
    columnDefs: [
        {
            field: 'age',
            filter: 'agNumberColumnFilter',
            filterParams: {
                // note: ensure you escape as if you were creating a RegExp from a string
                allowedCharPattern: '\\d\\-\\,',
                numberParser: text => {
                    return text == null ? null : parseFloat(text.replace(',', '.'));
                },
                numberFormatter: value => {
                    return value == null ? null : value.toString().replace('.', ',');
                },
            }
        }
    ],

    // other grid options ...
}
```

The `allowedCharPattern` is a regex of all the characters that are allowed to be typed. This is surrounded by square brackets `[]` and used as a character class to be compared against each typed character individually and prevent the character from appearing in the input if it does not match (in supported browsers).

The `numberParser` should take the user-entered text and return either a number if one can be interpreted, or `null` if not.

The `numberFormatter` should take a number (e.g. from the Filter Model) and convert it into the formatted text to be displayed, or `null` if no value.

An `allowedCharPattern` of `\\d\\-\\.` will give similar behaviour to the default `number` input.

The following example demonstrates custom number support:

- The first column shows the default Number Filter behaviour.
- The second column demonstrates custom number support, and uses commas for decimals and allows a dollar sign ($) to be included.
- Floating filters are enabled and also react to the configuration of `allowedCharPattern`.

#### Custom Number Support

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  INumberFilterParams,
  ModuleRegistry,
  NumberFilterModule,
  ValueFormatterParams,
  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, NumberFilterModule]);

const numberValueFormatter = function (params: ValueFormatterParams) {
  return params.value.toFixed(2);
};

const saleFilterParams: INumberFilterParams = {
  allowedCharPattern: "\\d\\-\\,\\$",
  numberParser: (text: string | null) => {
    return text == null
      ? null
      : parseFloat(text.replace(",", ".").replace("$", ""));
  },
  numberFormatter: (value: number | null) => {
    return value == null ? null : value.toString().replace(".", ",");
  },
};

const saleValueFormatter = function (params: ValueFormatterParams) {
  const formatted = params.value.toFixed(2).replace(".", ",");

  if (formatted.indexOf("-") === 0) {
    return "-$" + formatted.slice(1);
  }

  return "$" + formatted;
};

const columnDefs: ColDef[] = [
  {
    field: "sale",
    headerName: "Sale ($)",
    floatingFilter: true,
    valueFormatter: numberValueFormatter,
  },
  {
    field: "sale",
    headerName: "Sale",
    floatingFilter: true,
    filterParams: saleFilterParams,
    valueFormatter: saleValueFormatter,
  },
];

let gridApi: GridApi;

const gridOptions: GridOptions = {
  columnDefs: columnDefs,
  defaultColDef: {
    flex: 1,
    minWidth: 150,
    filter: true,
  },
  rowData: getData(),
};

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);
```

[Live example: Custom Number Support](https://www.ag-grid.com/examples/filter-number/custom-number-support/typescript)

## Number Filter Model

The Filter Model describes the current state of the applied Number Filter. If only one [Filter Condition](https://www.ag-grid.com/javascript-data-grid/filter-conditions/) is set, this will be a `NumberFilterModel`:

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filterType` | `'number'` |  |  | Filter type is always `'number'` |
| `filter` | `number \| null` |  |  | The number 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` | `number \| null` |  |  | Range filter `to` value. |
| `type` | `ISimpleFilterModelType \| null` |  |  | One of the filter options, e.g. `'equals'` |

If more than one Filter Condition is set, then multiple instances of the model are created and wrapped inside a Combined Model (`ICombinedSimpleModel<NumberFilterModel>`). A Combined Model looks as follows:

```ts
// A filter combining multiple conditions
interface ICombinedSimpleModel<NumberFilterModel> {
    filterType: string;

    operator: JoinOperator;

    // multiple instances of the Filter Model
    conditions: NumberFilterModel[];
}

type JoinOperator = 'AND' | 'OR';
```

An example of a Filter Model with two conditions is as follows:

```js
// Number Filter with two conditions, both are equals type
const numberEquals18OrEquals20 = {
    filterType: 'number',
    operator: 'OR',
    conditions: [
        {
            filterType: 'number',
            type: 'equals',
            filter: 18
        },
        {
            filterType: 'number',
            type: 'equals',
            filter: 20
        }
    ]
};
```

## Number Filter Options

The Number Filter presents a list of [Filter Options](https://www.ag-grid.com/javascript-data-grid/filter-conditions/#filter-options) to the user.

The list of options is as follows:

| 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 |

Note that the `empty` filter option is primarily used when creating [Custom Filter Options](https://www.ag-grid.com/javascript-data-grid/filter-conditions/#custom-filter-options). When 'Choose one' is displayed, the filter is not active.

The default option for the Number Filter is `equals`.

When providing filter options, the default filter option (or the first option if no default set) must be an option that displays an input or the `empty` filter option (as a filter option with no inputs would mean the filter is active by default).

## Range Input Validation and Error States

When using the `inRange` filter type, the grid performs input validation to ensure the bounds of the range produce a valid filter; that is, where the start value is less than the end value.

Where this is not the case, the last edited input will display a red border and a hover tooltip directing the user to enter a valid value. While the filter is in an invalid state, the filter will not be applied. Screen readers that respond to the `aria-invalid` attribute or the `ValidityState` of the input will detect the input as invalid.

## Number Filter Values

By default, the values supplied to the Number Filter are retrieved from the data based on the `field` attribute. This can be overridden by providing a `filterValueGetter` in the Column Definition. This is similar to using a [Value Getter](https://www.ag-grid.com/javascript-data-grid/value-getters/), but is specific to the filter.

| Property | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `filterValueGetter` | `string \| ValueGetterFunc` |  |  | Function or [expression](https://www.ag-grid.com/javascript-data-grid/cell-expressions/#column-definition-expressions). Gets the value for filtering purposes. |

## Applying the Number Filter

Applying the Number 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)

## Blank Cells

If the row data contains blanks (i.e. `null` or `undefined`), by default the row won't be included in filter results. To change this, use the filter params `includeBlanksInEquals`, `includeBlanksInNotEqual`, `includeBlanksInLessThan`, `includeBlanksInGreaterThan` and `includeBlanksInRange`. For example, the code snippet below configures a filter to include `null` for equals, but not for less than, greater than or in range (between):

```js
const filterParams = {
    includeBlanksInEquals: true,
    includeBlanksInNotEqual: false,
    includeBlanksInLessThan: false,
    includeBlanksInGreaterThan: false,
    includeBlanksInRange: false,
};
```

In the following example you can filter by age and see how blank values are included. Note the following:

- Column **Age** has both `null` and `undefined` values resulting in blank cells.
- Toggle the controls on the top to see how `includeBlanksInEquals`, `includeBlanksInNotEqual`, `includeBlanksInLessThan`, `includeBlanksInGreaterThan` and `includeBlanksInRange` impact the search result.

#### Number Null Filtering

```ts
import {
  ClientSideRowModelModule,
  ColDef,
  GridApi,
  GridOptions,
  INumberFilterParams,
  ModuleRegistry,
  NumberFilterModule,
  TextFilterModule,
  ValueGetterParams,
  createGrid,
  enableDevValidations,
} from "ag-grid-community";

// Enable extended validations only for development
if (process.env.NODE_ENV !== "production") {
  enableDevValidations();
}

ModuleRegistry.registerModules([
  TextFilterModule,
  ClientSideRowModelModule,
  NumberFilterModule,
]);

const originalColumnDefs: ColDef[] = [
  { field: "athlete" },
  {
    field: "age",
    maxWidth: 120,
    filter: "agNumberColumnFilter",
    filterParams: {
      includeBlanksInEquals: false,
      includeBlanksInNotEqual: false,
      includeBlanksInLessThan: false,
      includeBlanksInGreaterThan: false,
      includeBlanksInRange: false,
    } as INumberFilterParams,
  },
  {
    headerName: "Description",
    valueGetter: (params: ValueGetterParams) => `Age is ${params.data.age}`,
    minWidth: 340,
  },
];

let gridApi: GridApi;

const gridOptions: GridOptions = {
  columnDefs: originalColumnDefs,
  defaultColDef: {
    flex: 1,
    minWidth: 100,
  },
  rowData: [
    {
      athlete: "Alberto Gutierrez",
      age: 36,
    },
    {
      athlete: "Niall Crosby",
      age: 40,
    },
    {
      athlete: "Sean Landsman",
      age: null,
    },
    {
      athlete: "Robert Clarke",
      age: undefined,
    },
  ],
};

function updateParams(toChange: string) {
  const value: boolean = (
    document.getElementById(`checkbox${toChange}`) as HTMLInputElement
  ).checked;
  originalColumnDefs[1].filterParams[`includeBlanksIn${toChange}`] = value;

  gridApi!.setGridOption("columnDefs", originalColumnDefs);
}

const gridDiv = document.querySelector<HTMLElement>("#myGrid")!;
gridApi = createGrid(gridDiv, gridOptions);

if (typeof window !== "undefined") {
  // Attach external event handlers to window so they can be called from index.html
  (<any>window).updateParams = updateParams;
}
```

[Live example: Number Null Filtering](https://www.ag-grid.com/examples/filter-number/number-null-filtering/typescript)

## Data Updates

The Number Filter is not affected by data changes. When the grid data is updated, the filter value will remain unchanged and the filter will be re-applied based on the updated data (e.g. the displayed rows will update if necessary).