Find allows for values to be searched within the grid, with all matches highlighted and navigable, similar to find (^ Ctrl + F) within the browser.
Find is only compatible with the Client-Side Row Model.
Enabling Find
Find is enabled by setting the grid option findSearchValue with the text to be searched for.
Text to find within the grid. |
<ag-grid-angular
[findSearchValue]="findSearchValue"
/* other grid options ... */ />
this.findSearchValue = 'rowing';The grid API methods findNext(), findPrevious(), and findGoTo(matchNumber) can be used to move between the matches.
Go to the next match. |
Go to the previous match. |
Go to the provided match (first match is 1). |
Changing the Find search value, changing the active match, or updates to the grid that cause changes to the visible cells (e.g. changing columns/rows) trigger the findChanged event. The event contains details on the active match, as well as the total number of matches.
See findChanged for more details. |
The active match and the total number of matches can also be retrieved via the API.
Get the total number of matches. |
Get the active match, or undefined if no active match. |
Using Find with Cell Components
By default, Find searches within the Formatted Value of the cell, or the raw cell value if there is no Value Formatter. This is what is displayed in the cell by default.
Cell Components may display text that does not appear in the cell value. To enable Find to search within this additional text, the getFindText callback can be implemented on the Column Definition. Find will search within this value for matches.
When using Find with custom cell renderers, this allows providing a custom value to search within.
E.g. if the cell renderer is displaying text that is different from the cell formatted value.
Returning null means Find will not search within the cell. |
<ag-grid-angular
[columnDefs]="columnDefs"
/* other grid options ... */ />
this.columnDefs = [
{
field: 'year',
getFindText: params => `Year is ${params.value}`,
}
];When providing a custom cell component, the component is responsible for highlighting any matches and active matches within the cell. The grid API provides the following methods to help with this.
Get the number of matches within the provided cell. |
Get the parts of a cell value, including matches and active match.
Used for custom cell components. |
The following example demonstrates a custom cell component in the Year column, which uses the features described above. The custom cell component reuses the grid CSS classes ag-find-match and ag-find-active-match to apply the same styling as the default grid cell component.
Find does not work with the Animate Show Changed Cell Component or the Animate Slide Cell Component. If using these, provide a getFindText that returns null to exclude them from the search results. The same approach should also be used if manually specifying agCheckboxCellRenderer.
Customising Find
Find can be customised by providing an object of type FindOptions to the grid option findOptions.
Match values in the current page only (when pagination enabled).
|
Match case of values.
|
<ag-grid-angular
[findOptions]="findOptions"
/* other grid options ... */ />
this.findOptions = {
caseSensitive: true,
currentPageOnly: true,
};The following example demonstrates performing a case sensitive search, and finding matches within the current page only:
Content to Search
Find is designed to search within "visible" cell contents.
Searching is not performed within hidden columns. Columns not displayed due to Column Groups being expanded/collapsed are counted as being hidden.
The rows are searched after filtering and sorting have been performed.
Searching will be performed within the children of Collapsed Row Groups. When the active match is set to a child row within a collapsed group, the group is expanded (along with its parents if necessary).
When using Row Pagination, searching will be performed across all pages by default.
See the Customising Find section for an example of using Find with Row Grouping, as well as how to customise behaviour for Pagination.
Detail Rows / Grids and Full Width Rows are not searched.