Global Search

Global search is the grid's fast, dataset-wide search surface. Unlike a column filter, it searches across the participating fields of each record and produces one search criterion for the complete dataset view.

Use it for the familiar find anything in this data view experience: customer name, contact, city, status, identifier, date, or another value that participates in the dataset search contract.

Global search modes and view composition

Loading FDC sample…

import 'package:flutter_data_components/fdc.dart';

FdcGrid(
  dataSet: customers,
  options: const FdcGridOptions(
    readOnly: true,
    allowColumnSorting: true,
  ),
  header: const FdcGridHeader(
    filters: FdcGridHeaderFilters(
      visible: true,
      initiallyVisible: true,
    ),
  ),
  toolbar: const FdcGridToolbar(
    items: <FdcGridItem>[
      FdcGridSearchBar(
        placement: FdcGridItemPlacement.start,
        mode: FdcGridSearchBarMode.advanced,
        matchMode: FdcSearchMode.anyWord,
        caseSensitive: false,
        debounceDuration: Duration(milliseconds: 350),
        debouncePolicy: FdcDebouncePolicy.adaptive,
      ),
    ],
  ),
  columns: customerColumns,
);

// Search is dataset state, so the same view can also be controlled in code.
await customers.search.apply(
  'Seattle Technology',
  mode: FdcSearchMode.allWords,
  caseSensitive: false,
);

await customers.search.clear();

Try these searches in the sample:

Search	Mode	What it demonstrates
`Seattle Technology`	Any word	Rows matching either token
`Seattle Technology`	All words	Tokens can match across different fields of the same row
`New York`	Phrase	The complete phrase must occur in one participating field
`Active`	Exact phrase	A complete field value must equal the search phrase
`North`	Starts with	A participating field must begin with the phrase

The sample also keeps header filters and column sorting enabled. Search, filter, and sort are independent dataset view criteria: they compose rather than replace one another.

The built-in search surface is FdcGridSearchBar. Place it in an FdcGridToolbar like any other grid item:

FdcGrid(
  dataSet: customers,
  toolbar: const FdcGridToolbar(
    items: <FdcGridItem>[
      FdcGridSearchBar(
        placement: FdcGridItemPlacement.start,
        mode: FdcGridSearchBarMode.advanced,
      ),
    ],
  ),
  columns: customerColumns,
)

The default toolbar already contains one search bar. Define items when you want explicit control over toolbar composition or search behavior.

A toolbar can contain at most one visible FdcGridSearchBar. Global search is a singleton feature of the bound grid view, not an independent per-widget filter.

Simple and advanced modes

The search bar has two UI modes.

Advanced mode

const FdcGridSearchBar(
  mode: FdcGridSearchBarMode.advanced,
  matchMode: FdcSearchMode.anyWord,
  caseSensitive: false,
)

Advanced mode exposes the case-sensitivity toggle and match-mode menu to the user. The configured matchMode and caseSensitive values are the initial search semantics.

Use this mode for data exploration screens where users benefit from changing how terms are interpreted.

Simple mode

const FdcGridSearchBar(
  mode: FdcGridSearchBarMode.simple,
  matchMode: FdcSearchMode.phrase,
  caseSensitive: false,
)

Simple mode shows only the search field and clear action. The configured match mode and case sensitivity still apply, but users cannot change them from the toolbar.

Use it when product semantics should stay fixed and the search box should remain compact.

Match modes

FdcSearchMode controls how the search text is matched across participating fields.

Mode	Semantics	Typical use
`phrase`	The complete phrase must be contained in at least one field	Names, addresses, free text
`allWords`	Every token must match somewhere across the row's participating fields	Narrowing multi-term discovery
`anyWord`	At least one token must match somewhere across the row	Broad discovery
`exactPhrase`	One complete field value must equal the phrase	Codes, statuses, exact labels
`startsWith`	At least one field value must start with the phrase	Prefix lookup and quick navigation

The distinction between phrase and allWords is important. For a row with company Northstar Systems, city Seattle, and industry Technology:

Seattle Technology in phrase mode does not match because neither individual field contains that complete phrase;
the same text in allWords mode matches because both tokens are found somewhere across the same record.

Case sensitivity

Search is case-insensitive by default:

const FdcGridSearchBar(
  caseSensitive: false,
)

Set caseSensitive: true when letter case is meaningful for the application. In advanced mode the user can toggle case sensitivity from the search controls; in simple mode the configured value remains fixed.

Debounce policies

Search input can be applied automatically while the user types or only after explicit submission.

const FdcGridSearchBar(
  debounceDuration: Duration(milliseconds: 350),
  debouncePolicy: FdcDebouncePolicy.adaptive,
)

Three policies are available:

Policy	Behavior
`adaptive`	Uses `debounceDuration` as the base delay and can increase the effective delay for larger views
`fixed`	Always uses the configured delay as-is
`disabled`	Keeps edits local until the user explicitly submits with Enter/Search

adaptive is the general-purpose default. It reduces unnecessary repeated query work while keeping interactive search responsive.

For remote APIs with explicit request cost or strict rate limits, disabled is often the clearest policy:

const FdcGridSearchBar(
  debouncePolicy: FdcDebouncePolicy.disabled,
)

The user can type freely and submit the completed query explicitly.

Keyboard behavior

When the toolbar exposes a visible search bar:

Ctrl+F on Windows/Linux focuses the grid search;
Cmd+F on macOS focuses the grid search;
Enter submits immediately;
Escape closes the search interaction and restores grid focus when appropriate.

This shortcut targets the grid's own search surface rather than requiring users to reach for the pointer.

Global search is separate from field filtering:

Global search
    AND
Active field filters
    THEN
Sort order

Conceptually, a row must satisfy both the global search criterion and all active filters. Sorting then orders the resulting view.

This separation is useful in real data screens. A user can globally search for Seattle, filter status to Active, and then sort by credit limit without losing any of the other criteria.

Clearing global search clears only the search state. It does not clear column filters or sorting.

Local and paged execution

The toolbar search writes to the dataset search API. Execution follows the dataset's query model:

local and memory-backed views evaluate search against the local dataset view;
adapter-backed paged datasets route search through the adapter query path;
search is applied before paging so a page represents results from the searched view, not a search over only the currently loaded page.

For adapter-backed data, the backend or adapter defines the concrete query translation. Keep its search behavior semantically aligned with the application UI and document backend-specific limitations where they exist.

Control search from code

The toolbar is only one UI surface over dataset search state. The same search can be applied programmatically:

await customers.search.apply(
  'Seattle Technology',
  mode: FdcSearchMode.allWords,
  caseSensitive: false,
);

Restrict search to selected fields when the workflow requires a narrower scope:

await customers.search.apply(
  'smith',
  fields: <String>[
    'company_name',
    'contact_name',
    'city',
  ],
);

Inspect or clear the active state through the dataset API:

final hasSearch = customers.search.active;
final searchState = customers.search.state;

await customers.search.clear();

Programmatic field scoping is a dataset capability. The built-in grid toolbar search uses the dataset-wide search surface; use the dataset API or a custom search UI when a screen requires explicit field selection.

Choosing sensible defaults

For a broad operational grid, a strong default is:

const FdcGridSearchBar(
  mode: FdcGridSearchBarMode.advanced,
  matchMode: FdcSearchMode.anyWord,
  caseSensitive: false,
  debounceDuration: Duration(milliseconds: 350),
  debouncePolicy: FdcDebouncePolicy.adaptive,
)

For a focused business lookup, prefer fixed semantics:

const FdcGridSearchBar(
  mode: FdcGridSearchBarMode.simple,
  matchMode: FdcSearchMode.startsWith,
  caseSensitive: false,
  debouncePolicy: FdcDebouncePolicy.fixed,
)

For a costly remote search endpoint, require explicit submission:

const FdcGridSearchBar(
  mode: FdcGridSearchBarMode.simple,
  matchMode: FdcSearchMode.phrase,
  debouncePolicy: FdcDebouncePolicy.disabled,
)

The best policy is determined by the interaction contract and query cost, not just dataset size.

Add search to the toolbar​

Simple and advanced modes​

Advanced mode​

Simple mode​

Match modes​

Case sensitivity​

Debounce policies​

Keyboard behavior​

Search, filters, and sorting​

Local and paged execution​

Control search from code​

Choosing sensible defaults​

Related topics​

Add search to the toolbar