AdapTable Version:

Framework:

Configuring Quick Search

Summary

AdapTable allows users (both at run time and design time) to configure aspects of Quick Search including:
- a custom Quick Search implementation
- which columns and cells are included in quick search
- whether searches are saved between sessions

Essentially Quick Search is a very straightforward operation.

It simply highlights any cells in any column which contain the matching term using a default style.

And AdapTable will re-apply an active Quick Search when the application re-opens.

However AdapTable provides many configuration options so Search can meet precise requirements.

Searching on Raw Value

By default Quick Search will return true or false if the display value in a cell contains the search text.

This means, for example, that searching for 5000 in a cell with a display value of £5,000 will return false (due to the missing comma).

As a result, sometimes this default behaviour does not meet the particular requirements.

Developers can tell Quick Search to search on the raw value, instead, by using the getCellSearchText property in Quick Search Options.

getCellSearchText

(quickSearchContext: QuickSearchContext) => boolean

Function enabling custom Quick Search implementations

Use this property to override AdapTable's default Quick Search implementation: which returns true if the Cell's display value contains the Quick Search text.

The function receives a QuickSearchContext object and returns a boolean:

getCellSearchText?(quickSearchContext: QuickSearchContext): boolean;

The QuickSearchContext object contains 2 properties:

Property	Description
gridCell	Cell being checked
quickSearchValue	Current Quick Search Text
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

As noted, the most common use case is to use the property to search on the raw value:

// Search on cell raw value for Github Stars
const adaptableOptions: AdaptableOptions = {
  quickSearchOptions: {
    getCellSearchText(context: QuickSearchContext) {
      return context.gridCell.column.columnId == 'github_stars'
        ? context.gridCell.rawValue
        : context.gridCell.displayValue;
    },
  }
}

However it is also possible to leverage this function for more bespoke searching requirements (see the the section below for more details):

// Enable quick search text with commas and search for any matches
const adaptableOptions: AdaptableOptions = {
  quickSearchOptions: {
    getCellSearchText(context: QuickSearchContext) {
      const values = context.quickSearchValue
        .split(',')
        .map(x => x.trim().toLocaleLowerCase())
        .filter(x => Boolean(x));
      const isMatch: boolean = values.some(x =>
        String(context.gridCell.displayValue).toLocaleLowerCase().includes(x)
      );
      return isMatch ? context.quickSearchValue : context.gridCell.rawValue;
    },
}

Quick Search Raw Value

Fork Fork

In this demo we use the getCellSearchText function to tell AdapTable to search using raw cell value on the Github Stars column
We provide a distinctive Number Display Format for Github Stars and Github Watchers
We search for "1794" and the first cell in the Github Stars is returned because it matches the raw value

Try It Out

Search for "667" and note that the first cell in the Github Watchers does not return a match - since that doesnt match its (default) display value

Providing Custom Quick Search

In addition to enabling searching on raw value (see section above), the getCellSearchText property in Quick Search Options also allows developers to provide their own, bespoke, Quick Search implementation.

Caution

A bespoke Quick Search implementation should not be provided if you are running Quick Search as a Filter
This is because AG Grid's native filter evaluation is used, which will be unaware of the bespoke implementation

This is particularly useful if you want to search for patterns, or across multiple cells.

Another common use case is to allow commas (or pipes) so cells containing any of the search values are returned

Hint

When running a bespoke Quick Search, ensure that you set CellMatchStyle in Quick Search Initial State
This is required because AG Grid cannot style the matching text, so you there need to style the entire matching cell

Bespoke Quick Search

Fork Fork

In this demo we provide a bespoke Quick Search implementation by using the getCellSearchText in Quick Search Options
Our implementation allow users to search using comma separated values, which we achieve by changing the Quick Search Value to be that of the search text for matching cells (so it returns true)
We set an initial Quick Search for 'js, html' and we see that all cells which contain either of those search terms are matched
We also provide a CellMatchStyle in Quick Search Initial State to highlight matching cells

Caution

If performing a bespoke Quick Search, the up / down arrows enabling cycling through the result set will not work
Additionally 2 of the Quick Search Styles - TextMatchStyle & CurrentTextMatchStyle - are ignored

Excluding Cells from Quick Search

By default every visible Cell in AG Grid will be included in Quick Search.

This can be changed by setting the isCellSearchable function in Quick Search Options.

Hint

This is particularly useful in cases where an AG Grid Cell Component causes false positives in the Search results

isCellSearchable

(quickSearchContext: QuickSearchContext) => boolean

Function enabling specific Cells to be excluded from Quick Search

The function receives a QuickSearchContext object and returns a boolean:

isCellSearchable?: (quickSearchContext: QuickSearchContext) => boolean;

The QuickSearchContext object contains 2 properties:

Property	Description
gridCell	Cell being checked
quickSearchValue	Current Quick Search Text
adaptableContext	Custom application Context provided in `AdaptableOptions.adaptableContext`

// Exclude 'Language' Column and all ReadOnly columns from  Quick Search results
const adaptableOptions: AdaptableOptions = {
  quickSearchOptions: {
    isCellSearchable: (context: QuickSearchContext) => {
      if (context.gridCell.column.columnId === 'language' || context.gridCell.column.readOnly) {
          return false;
      }
      return true;
    },
  }
}

Caution

This function should not be provided if you are running Quick Search as a Filter
AG Grid's native filter evaluation will be unaware of these Cell and Column exclusions and use the full set

Quick Search Exclude Cells

Fork Fork

In this demo we have provided an implementation for the isCellSearchable function in order to exclude:
- the Description column (excluded by name)
- any columns with a data type of Text Array (which includes the Topics column)

Saving Quick Search Text

AdapTable automatically saves the last run Quick Search value into AdapTable State.

It will then re-apply the Quick Search when the Application is next reloaded.

If this behaviour is not desired, set the clearQuickSearchOnStartUp property in Quick Search Options to true.

clearQuickSearchOnStartUp

Default: false

boolean

Clears saved Quick Search when AdapTable loads

This boolean property will ensure a saved Quick Search is cleared on application restart.

Hint

The clearFiltersOnStartUp property in Filter Options will clear any saved Column Filters
The clearGridFilterOnStartUp property in Grid Filter Options will clear a saved Grid Filter

// Clear the previously saved Quick Search when AdapTable restarts
const adaptableOptions: AdaptableOptions = {
    quickSearchOptions: {
        clearQuickSearchOnStartUp: true
    }
}

Changing Quick Search Placeholder

The default placeholder text in each Quick Search input is Search.

This can be modified via the quickSearchPlaceholder property in Quick Search Options

quickSearchPlaceholder

Default: Search

string

Sets the placeholder used in Quick Search inputs

This string property can set a custom placeholder in Quick Search inputs.

// Set the Quick Search placeholder to be 'Find'
const adaptableOptions: AdaptableOptions = {
    quickSearchOptions: {
        quickSearchPlaceholder: 'Find'
    }
}

Quick Search Placeholder

Fork Fork

In this demo we have changed the quickSearchPlaceholder to be 'Find Text'

Expand to see more

Floating Quick Search

Typically Quick Search is performed using the dedicated Quick Search input.

This is available, most typically in the Dashboard, but in multiple other places in AdapTable.

However there is also an option to use Floating Quick Search.

Hint

This is especially useful when, for screen real estate reasons, the Dashboard and other UI components are hidden
Another common use case is advanced users who do everything via the keyboard and try to reduce mouse usage

The Floating Quick Search appears in the top right of the screen (similar to its position in the Dashboard).

Note

Floating Quick Search is opened by calling showFloatingQuickSearch in Quick Search API
It is closed by calling hideFloatingQuickSearch in Quick Search API or by pressing the ESC key

Floating Quick Search

Fork Fork

In this demo we listen to the KeyDown Event for the key combination: 'metaKey + shiftKey + s',
When that happens, we open the Floating Quick Search using the showFloatingQuickSearch function in Quick Search API
We have hidden the Dashboard to mimic a typical use case for this functionality

Expand to see the key bindings

export const onAdaptableReady = ({adaptableApi}: AdaptableReadyInfo) => {
  document.addEventListener('keydown', event => {
    const {key, shiftKey, metaKey} = event;

    // metaKey is 'command key' on Mac and 'windows key' on PC
    if (key === 's' && metaKey && shiftKey) {
      event.preventDefault();
      adaptableApi.quickSearchApi.showFloatingQuickSearch();
    }
  });
};

Try It Out

Click the Meta Key (windows key on PC, Command Key on Mac), Shift and 's' and see the Floating Quick Search
Click the Escape Key to close the Floating Quick Search

FAQ

Can we limit Quick Search to particular Cells or Column data types? Yes, you can. By default Quick Search works across ALL Cells in AdapTable. To exclude a Column or Cell, use the isCellSearchable property in Quick Search Options.

PreviousQuick Search as Filter NextTechnical Reference

Framework: