MainGrid

The MainGrid component is a standalone grid for displaying Dataverse records. Unlike SubGrid, it does not require a parent RecordContext — it loads records directly from a specified table or view.

Loading by Table Name

Set the TableName parameter to automatically load all public views for that table. The first default view is selected initially.

Loading by View IDs

Use ViewIds and DefaultViewId to control exactly which views are available and which one is selected on load. You can also provide CustomViewDefinitions with inline FetchXML to define views directly in code.

Custom Views with FetchXML

Use CustomViewDefinitions to define views with custom FetchXML queries. This is useful for views that include filters based on the current user, linked entities, or other dynamic criteria.

Note

The Id for a custom GridViewDefinition must be a unique random GUID that does not correspond to an existing Dataverse view. If it matches an existing view ID, the Dataverse view will take precedence and the custom definition will be ignored.

DisplayName

Set DisplayName on a GridViewDefinition to provide a default label for the view in the dropdown selector without requiring a localization file entry. If a localization key exists at tables.{TableName}.views.{Id}.label, it takes precedence over DisplayName. This is useful for custom views where you want a readable name immediately without adding a localization entry.

Toolbar Buttons

The MainGrid supports the same toolbar buttons as SubGrid. For standalone grids, NavigateNewRecordGridButton and NavigateOpenRecordGridButton are commonly used to navigate to separate form pages. See the Grid Buttons documentation for a complete reference of all available buttons and their configuration options.

Search Box Behavior

When the user types in the grid's search box, the configured view is automatically re-queried with additional filter conditions applied to every search-eligible column shown in the view. The conditions are joined with OR logic, so a record is included if any of its visible columns match the search term. The default match semantics differ depending on the column type.

Text and Lookup Columns

Text columns (string fields) and lookup columns (matched against the target record's primary name) use a starts with search by default. Typing joh matches values that begin with joh — for example John or Johnson. The match is delegated to FetchXML's like operator, which is case-insensitive in Dataverse.

Use * as a wildcard for more flexible matching. Typing *hn performs a contains-style match (e.g. John, Johnson); typing j*n matches values where any characters can appear between the j and the n (e.g. John, Joneson). The wildcard is converted to FetchXML's % wildcard at query time.

Choice Columns

Choice columns (option sets / picklists) and multi-select choice columns are matched against the localized display label of each option rather than the underlying integer value. Labels are compared case- and accent-insensitively in the current user's culture, so typing cafe will match an option labelled Café. When one or more option labels match, the query emits a FetchXML condition against the matching option values — an in condition for single-select choice columns, or a contain-values condition for multi-select choice columns. When no labels match, the column contributes no condition (keeping the OR filter compact).

Choice columns honor the same * wildcard as text columns: by default the match is starts with (typing act matches Active), and a leading * switches to contains (typing *act additionally matches Inactive). Matching rows have the matched substring highlighted in the grid, exactly like text-column matches.

Numeric and Money Columns

Numeric columns — int, big int, decimal, double, and money — support comparison operators in the search term. The search box parses an optional leading operator and applies the corresponding FetchXML condition operator:

• = 100 or just 100  —  equal (the default when no operator is specified)
• > 100  —  greater than
• < 100  —  less than
• >= 100  —  greater than or equal
• <= 100  —  less than or equal

Note

Search conditions for every column type are added to the same OR filter group, so the same search term is evaluated against text columns, lookup columns, choice columns, and numeric columns simultaneously. Typing 100 in a grid that has both a name column and an amount column will match records whose name starts with 100 or whose amount equals 100. The search filter is layered on top of the view's existing filter, so view-level constraints (such as a statecode = 0 filter) are always preserved.

Disabling Search

Set AllowSearch="false" on the grid to hide the search box entirely. This is useful for grids that contain only a small fixed set of records, or where filtering is handled externally (for example via a custom toolbar).

Paging Mode

The grid supports two paging strategies via the PagingMode parameter (Blazor) / pagingMode prop (React). Both modes use the same underlying view, FetchXML, sorting, and search — only the way rows are revealed to the user differs.

• Paged (default) — a classic Prev / Next footer with a page-size selector. Best for shorter result sets and for cases where the user wants to jump around by page number or share a deep-linked page in the URL.
• Virtualize — infinite scroll. The pager footer is hidden, rows accumulate as the user scrolls past the rendered bottom, and the next page fetches automatically. A read-only "Showing 1-N of M" counter replaces the pager once a total is available. Best for long lists where the user scans rather than navigates by page.

Opt in by setting the paging mode on the grid:

Tradeoffs

• No jump-to-page. Virtualize mode always starts at the first page and pulls forward; consumers can no longer skip to page N. If you need explicit page navigation, stay on Paged.
• Page is not persisted. Since the user's scroll position isn't a discrete page concept, PersistedStateQueryParameter omits the p key in virtualize mode. Selected view, sort, and (opt-in) search still round-trip through the URL.
• Search and sort still work, but they reset the scrolled-in accumulator — changing the active view, applying a new sort, or typing in the search box drops the loaded rows and re-fetches from the top.
• Hides the pager / page-size selector. The page-size selector is replaced by a fixed chunk size; set the initial value via DefaultItemsPerPage (Blazor) / pageSize (React) to control how many rows are fetched per scroll-triggered page.

Full Size Mode

Set FullSize="true" to make the grid expand to fill the full height of its parent container. This is useful when the grid is the main content of a page.

Persisting Grid State

Set PersistedStateQueryParameter to a query-parameter name (e.g. "gridState") and the grid will mirror its interactive state into a single URL parameter under that name. Every user-driven change — switching the selected view, paging, resizing the page size, clicking column headers to sort, or (opt-in) typing in the search box — re-encodes the state and replaces the URL parameter in place. When the page is opened with the parameter present (bookmark, shared link, refresh), the grid reads the parameter on first load and restores all of the captured state before fetching data.

What Gets Persisted

The query parameter encodes a compact JSON object with one short key per piece of state. Keys are deliberately abbreviated to keep bookmarked URLs short. Fields that match their natural defaults are omitted, so a grid sitting at page 1 with no sort and no search produces a much smaller blob than one with all five fields populated.

• v — the selected view's GUID (lowercase, hyphenated, no braces). Matches one of the ViewIds / CustomViewDefinitions entries the grid was configured with.
• p — the 1-based page number. Omitted when the user is on page 1 (the default).
• ps — the number of rows per page. Reflects the user's last selection in the page-size dropdown; omitted when it matches the grid's DefaultItemsPerPage.
• s — an ordered array of sort directives. Each entry has c (column logical name) and an optional d (set to true for descending; ascending is the unmarked default, so d is omitted in that case). Empty / unsorted state omits the field entirely. Multi-column sort is preserved in precedence order.
• q — the current search-box text. Only included when the grid was configured with IncludeSearchInPersistedState="true" AND the box has a non-empty value. Off by default since search terms can be sensitive (e.g. customer names in a CRM context).

URL Encoding

The state is serialized as compact JSON (no whitespace) and URL-encoded into the query parameter. A grid showing page 3 of a contact view, sorted by lastname ascending then createdon descending, with search "smith" enabled would round-trip the following payload:

After URL-encoding, the actual address bar value looks like this (the framework calls encodeURIComponent on the JSON string before writing it):

Default-Value Stripping

The encoder strips any field that matches its natural default before serializing. Page 1 drops p, an empty sort list drops s, an unmarked-ascending sort drops d, and an empty search drops q. A freshly-loaded grid with no user interaction encodes to a blob containing only v and ps — keeping bookmarked URLs from growing for state the consumer hasn't touched.

Browser History Behavior

State changes update the URL with history.replaceState — they don't push new entries onto the back stack. This means hitting Back from a grid page returns to the previous distinct page (the user's nav origin), not to the previous sort/page combination. The trade-off is intentional: a single grid session can produce dozens of state changes, and pushing each as a navigation entry would make the Back button effectively useless across the rest of the app.

Enabling Search Persistence

By default, search text is excluded from the URL so the parameter is safe to share even when the grid is filtering by a sensitive term. Set IncludeSearchInPersistedState="true" to include the current search box value in the encoded payload (added as the q field above). Once enabled, search becomes part of the bookmarkable state — the user can copy the URL and the recipient lands on the same view, page, sort, AND filter combination.

Cross-Stack Compatibility

The encoded JSON shape is identical between the Blazor and React grid implementations — same parameter name, same keys (v / p / ps / s / q), same value semantics. A link produced by one stack is consumable by the other, so an organization that runs both surfaces (e.g. a public-facing React portal alongside an internal Blazor admin app) can share grid URLs between them without any per-stack translation layer.

Multiple grids on one page

Two grids on the same page must use different PersistedStateQueryParameter names. Each grid only reads and writes its own parameter, so reusing the same name would have both grids fighting over the same URL slot — last write wins and the other grid loses its state on every change. A typical convention is to name the parameter after the grid's role (e.g. contactsState + accountsState).

Multi-Table Grids

A MainGrid can display views from different tables by including view IDs from multiple tables in the ViewIds collection. When the user switches views, the grid automatically loads the correct table's data. Use the OnClick callback on navigation buttons to dynamically set the URL based on the selected view's table name.