Toolbar

The grid toolbar is an ordered command surface above the grid. It can host global search, the grid main menu, export, paging controls, standard action buttons, separators, spacers, and fully custom widgets.

Toolbar composition

Loading FDC sample…

FdcGrid(
  dataSet: customers,
  toolbar: FdcGridToolbar(
    items: <FdcGridItem>[
      const FdcGridSearchBar(
        placement: FdcGridItemPlacement.start,
        mode: FdcGridSearchBarMode.advanced,
      ),
      FdcGridButton(
        id: 'add-customer',
        placement: FdcGridItemPlacement.start,
        icon: Icons.person_add_alt_1_outlined,
        label: 'Add customer',
        tooltip: 'Append a new customer record',
        onPressed: () => customers.append(),
      ),
      FdcGridButton(
        id: 'delete-customer',
        placement: FdcGridItemPlacement.start,
        icon: Icons.person_remove_outlined,
        label: 'Delete customer',
        tooltip: 'Delete the current customer record',
        onPressed: () => customers.delete(),
      ),
      const FdcGridMainMenuButton(
        placement: FdcGridItemPlacement.start,
      ),
      FdcGridExportButton(
        visible: true,
        placement: FdcGridItemPlacement.end,
        formats: const <FdcExportFormat>[
          FdcExportFormat.csv,
          FdcExportFormat.json,
          FdcExportFormat.xml,
        ],
        onExport: (result) {
          // Save, share, or download through platform-specific code.
        },
      ),
    ],
  ),
  columns: customerColumns,
);

The sample starts with global search, followed immediately by Add Customer and Delete Customer actions on the left. The grid menu remains in the same start zone, while export stays at the end. Try searching, adding or deleting a customer, opening the grid menu, or generating an export.

Basic configuration

FdcGridToolbar is visible by default and its default item list contains one FdcGridSearchBar. Define items when you want full control over composition:

FdcGrid(
  dataSet: customers,
  toolbar: FdcGridToolbar(
    items: <FdcGridItem>[
      const FdcGridSearchBar(
        placement: FdcGridItemPlacement.start,
        mode: FdcGridSearchBarMode.advanced,
      ),
      FdcGridButton(
        placement: FdcGridItemPlacement.start,
        icon: Icons.person_add_alt_1_outlined,
        label: 'Add customer',
        onPressed: customers.append,
      ),
      FdcGridButton(
        placement: FdcGridItemPlacement.start,
        icon: Icons.person_remove_outlined,
        label: 'Delete customer',
        onPressed: customers.delete,
      ),
      const FdcGridMainMenuButton(
        placement: FdcGridItemPlacement.start,
      ),
      FdcGridExportButton(
        visible: true,
        placement: FdcGridItemPlacement.end,
      ),
    ],
  ),
  columns: customerColumns,
)

The order in items is preserved inside each placement zone. Placement is therefore the first level of layout, and list order is the second.

Three placement zones

Every FdcGridItem has a placement:

Placement	Purpose
FdcGridItemPlacement.start	Primary commands and navigation anchored to the leading edge
FdcGridItemPlacement.center	Balanced actions or contextual controls
FdcGridItemPlacement.end	Secondary commands, export, or paging controls

The toolbar and status bar use the same three-zone item model. This makes shared items such as paging controls easy to move from one bar to the other without changing their behavior.

Built-in toolbar items

Global search

FdcGridSearchBar connects directly to dataset search. The advanced mode exposes match-mode and case-sensitivity controls. See Global Search for match semantics, debounce policies, keyboard behavior, paging, and search/filter composition:

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

Use simple mode when the application should control those search semantics and the user only needs the text field and clear action.

A toolbar can contain at most one FdcGridSearchBar, because global search is a singleton grid feature.

Main menu

FdcGridMainMenuButton moves the grid main menu into the toolbar:

const FdcGridMainMenuButton(
  placement: FdcGridItemPlacement.start,
)

When a visible main-menu button exists in a visible toolbar, the grid suppresses the duplicate main-menu affordance in the header.

A toolbar can contain at most one FdcGridMainMenuButton.

Export

FdcGridExportButton exposes the built-in export pipeline:

FdcGridExportButton(
  visible: true,
  formats: const <FdcExportFormat>[
    FdcExportFormat.csv,
    FdcExportFormat.json,
    FdcExportFormat.xml,
  ],
  scope: FdcExportScope.currentView,
  columnMode: FdcGridExportColumnMode.visibleColumns,
  onExport: (result) {
    // Route result to platform-specific download or share code.
  },
)

The core grid generates the export result but intentionally leaves file saving or sharing to the application, because that workflow is platform-specific.

Standard buttons

Use FdcGridButton for application commands that fit the grid command surface:

FdcGridButton(
  id: 'append-customer',
  icon: Icons.person_add_alt_1_outlined,
  label: 'New customer',
  tooltip: 'Append a new customer record',
  onPressed: customers.append,
)

Set onPressed to null to use the normal disabled-button behavior.

Keep record-oriented actions close to the grid. Broader application navigation usually belongs in the surrounding screen toolbar rather than inside FdcGridToolbar.

Separators, spacing, and custom content

The shared item model includes:

• FdcGridSeparator for visual grouping;
• FdcGridSpacer for fixed horizontal space;
• FdcGridCustomItem for arbitrary widget content;
• FdcGridButton for standard icon or icon-and-label commands.

For example:

FdcGridCustomItem(
  placement: FdcGridItemPlacement.end,
  builder: (context) => const Chip(
    label: Text('Live'),
  ),
)

Use custom items sparingly. Built-in items inherit the toolbar theme and integrate with grid runtime state automatically.

Paging controls

Paged datasets can place these shared items in either the toolbar or status bar:

• FdcGridPagingNavigator.input(...)
• FdcGridPagingNavigator.numbered(...)
• FdcGridPagingRecordInfo(...)
• FdcGridPageSizeSelector(...)

Example composition:

FdcGridToolbar(
  items: <FdcGridItem>[
    const FdcGridSearchBar(
      placement: FdcGridItemPlacement.start,
    ),
    const FdcGridPagingRecordInfo(
      placement: FdcGridItemPlacement.end,
    ),
    FdcGridPagingNavigator.numbered(
      placement: FdcGridItemPlacement.end,
      visiblePageCount: 5,
    ),
  ],
)

Paging navigator items are not rendered for infinite paging mode, where numbered-page navigation is not meaningful.

Responsive composition

Toolbar items are measured at their natural width. When the grid becomes too narrow, the shared responsive layout protects the outer anchors:

1. center items disappear first;
2. end-zone items nearest the center are removed next;
3. start-zone items nearest the center are removed last.

This behavior keeps the most strongly anchored leading and trailing commands stable while the grid width changes. Put essential commands toward the outer edges of their zones and optional controls closer to the center.

Styling

Use FdcGridToolbar.style for local styling or the grid theme for application-wide defaults. The toolbar resolves text, icon, disabled, background, padding, search, and separator styling through FdcGridToolbarStyle.

Prefer theme-level customization when many grids should look the same. Use the local style property for one-off screens.

Related topics

• Global Search
• Status Bar
• Searching
• Paging
• Basic Usage