SubGrid

The SubGrid component displays Dataverse records related to a parent record via a specified relationship. It must be placed inside a RecordContext and requires a RelationshipName parameter that specifies which relationship to use.

Relationship Types

SubGrid supports both one-to-many (1:N) and many-to-many (N:N) relationships. The component automatically detects the relationship type and adjusts its behavior accordingly.

  • For 1:N relationships, the grid displays records from the related table that reference the parent record. Toolbar buttons like NewRecordGridButton, OpenRecordGridButton, and DeleteRecordGridButton are used to create, edit, and delete related records.
  • For N:N relationships, the grid displays associated records. Toolbar buttons like LinkExistingRecordGridButton and UnlinkExistingRecordGridButton are used to associate and disassociate records. Create and delete operations are automatically converted to associate and disassociate requests.

Views

Use ViewIds to specify which views are available in the view selector dropdown, and DefaultViewId to set the initially selected view. If neither is provided, the grid automatically loads all public views for the related table. You can also provide CustomViewDefinitions with inline FetchXML to define views directly in code.

React
Blazor

Toolbar Buttons

Add buttons to the grid toolbar using the Buttons render fragment. See the Grid Buttons documentation for detailed configuration options including dialog positioning, wizard forms, and save behavior. The following built-in buttons are available:

  • NewRecordGridButton — Opens a dialog form to create a new related record (1:N)
  • OpenRecordGridButton — Opens a dialog form to edit the selected record
  • DeleteRecordGridButton — Deletes selected records
  • LinkExistingRecordGridButton — Associates an existing record via a N:N relationship
  • UnlinkExistingRecordGridButton — Disassociates selected records from a N:N relationship
  • NavigateNewRecordGridButton — Navigates to a URL to create a new record
  • NavigateOpenRecordGridButton — Navigates to a URL to edit the selected record
React
Blazor

Inline Editing

Set AllowEdit="true" to enable a settings toggle that lets users switch to inline editing mode. When enabled, editable columns render as form controls directly in the grid. Inline editing is only supported for 1:N relationships.

React
Blazor

Paging & Search

The grid supports paged navigation with configurable page sizes via DefaultItemsPerPage and PageSizes. Search is enabled by default and can be disabled with AllowSearch="false".

React
Blazor

SubGrid (One to Many Relationship)

The following example shows a SubGrid displaying contacts related to an account via the contact_customer_accounts relationship. It includes buttons for creating, editing, and deleting contacts.

React example
Blazor example
All ContactsMy Contacts
New
All ContactsMy Contacts
New

Page size

102050100
Full Name
Mobile Phone
Email
Company Name
Age
Bradford Kiehn(878) 546-1743Bradford.Kiehn13@yahoo.comAbernathy - MacGyver64
Jaydon Baumbach(091) 769-5345Jaydon.Baumbach5@gmail.comAbernathy - MacGyver63
Karlee Kuphal(651) 890-0779Karlee11@yahoo.comAbernathy - MacGyver59
Keshawn Lubowitz(405) 079-0110Keshawn_Lubowitz@yahoo.comAbernathy - MacGyver24
Salma Yost(175) 474-8388Salma_Yost@yahoo.comAbernathy - MacGyver55
React TypeScript
Razor
AccountAndContactCustomViews.cs

SubGrid (Many to Many Relationship)

The following example shows a SubGrid displaying regions associated with an account via the ppp_Account_ppp_Region_ppp_Region many-to-many relationship.

React example
Blazor example
Active RegionsInactive Regions
Link Existing
Active RegionsInactive Regions
Link Existing

Page size

102050100
Name
No records found.
React TypeScript
Razor
React Blazor

SubGrid Class

Parameters

Name
Type
Default
Description
AllowChangingPageSizebool
True
When true, the user can change the number of items displayed per page.
AllowDownloadForFileColumnsbool
True
When true (the default), the grid renders a per-row download icon at the trailing edge of file and image column cells. Clicking it streams the file to the user's browser. Set to false to suppress the icon — for example on read-only audit grids where file export isn't allowed.
AllowEditbool
False
Should the option be available for the user to turn on inline editing for the grid.
AllowNavigateOnPrimaryNameClickbool
True
When true (the default) and the grid has a registered 'edit' button (a GridButton with IsOpenRecordButton=true), the cell that renders the table's primary-name column becomes a hyperlink. Clicking it dispatches the same per-row invocation that a row double-click would — so a user can jump to the edit form (or the navigated edit URL, depending on the registered button) without first selecting the row. Set to false to suppress the hyperlink and render the primary-name cell as plain text. Has no effect when no edit button is registered.
AllowNavigateOnRowDoubleClickbool
True
When true (the default) and the grid has a registered 'edit' button (a GridButton with IsOpenRecordButton=true), double-clicking a row invokes that button's OnClick for the row's record — opening the edit dialog or navigating to the edit URL, whichever the button does. Set to false to suppress the double-click handler. Has no effect when no edit button is registered.
AllowPreviewForFileColumnsbool
True
When true (the default), the grid renders a per-row 'eye' preview icon at the trailing edge of file and image column cells whose contents can be rendered inline (images, PDFs, plain text). Set to false to suppress the icon — for example on grids where the columns shouldn't double as a preview entry point.
AllowSearchbool
True
Should the user be allowed to search the grid.
BorderVisiblebool
True
Controls whether a visible border is rendered around the grid.
ButtonsRenderFragment?
Optional render fragment used to define the button toolbar displayed above the grid.
ColumnsRenderFragment?
Optional Components.GridColumns fragment carrying consumer-declared Components.GridColumn children. When supplied, the grid switches to replace mode: only the declared columns render (in declared order), the FetchXML projection is rewritten to match, and the underlying view's column list is ignored. null leaves the grid in its default behavior (auto-generate columns from the view's resolved column set).
CustomViewDefinitionsList<GridViewDefinition>?
Custom views to display in the dropdown.
DataSourceViewDataSource?
Optional shared Data.ViewDataSource. When set, the grid reads its rows + total count from the datasource instead of issuing its own RetrieveRecordsAsync(System.String) call — the same datasource can drive a sibling <DataverseChart> or a second grid so they all paginate / filter / search together off one round-trip. Standalone usage (no GridBase.DataSource) keeps the existing internal-state machine — the grid composes FetchXML and fetches via IPowerPortalsProService directly. What the datasource does NOT own: per-grid UI state (selected rows, pending row creates / updates / deletes, column widths). Those stay grid-local — two grids sharing one datasource can still have independent selection and per-grid pending edits. When ViewDataSource.Highlight is set (e.g. via a chart slice click in cross-filter 'highlight' mode), rows whose value in the highlighted column doesn't match are visually muted via a CSS class; the row data + selection are unaffected (the soft cross-filter is purely styling).
DefaultItemsPerPageint
50
Default number of records to load on a page.
DefaultViewIdGuid?
Id of the view that the grid should display upon initial load.
Editablebool
False
Is inline editing turned on for the grid.
FiltersIReadOnlyList<GridFilterBase>?
Additional server-side filters AND-merged onto the resolved view's FetchXML before paging / sorting / searching kick in. Forwarded to Query.IFetchXmlQueryComposer's FetchXmlQueryOptions.Filters, so each entry is dispatched by runtime type (e.g. Models.RelationshipFilter AND-merges a relationship link-entity). Typical use: the LinkExistingRecordGridButton picker passes a Models.RelationshipFilter with RelationshipFilterMode.ExcludeExistingRecords so already- linked records are hidden from the M2M lookup dialog. Combines additively with SubGrid's own internal relationship filter (which is built into the FetchXML directly rather than going through the composer's Filters slot) — both end up in the same query.
FullSizebool
False
When true, the grid expands to fill all available vertical space instead of using a fixed minimum height.
HidePagingbool
False
Force the page size and paging components to be hidden. Only do this when the number of items is known and the page size is set to something greater than the item count.
IncludeSearchInPersistedStatebool
False
When true, the active search text is included in the persisted state URL parameter (under the q field). Defaults to false — search terms can be sensitive, accumulate in browser history, and leak into HTTP referrers, so the grid keeps them out of the URL unless the consumer explicitly opts in. Has no effect when GridBase.PersistedStateQueryParameter is not set.
IsDirtybool
False
Indicates whether the grid has unsaved create, update, or delete operations pending.
LoadedRecordsIEnumerable<TableRecord>
Records currently rendered in the grid (the most recent page of results). Intended for toolbar commands that need to act on 'everything shown' — e.g. a bulk download button. Does not span pages; bulk-across-pages operations should run their own unpaged fetch instead.
MaxHeightstring?
Max Height that the grid control should expand to.
MinHeightstring?
300px
Minimum height that the grid control should occupy.
ModeGridMode
RecordSelection
Sets the behavioural mode of the grid, such as default interaction or record-selection mode.
PageSizesIEnumerable<int>
Collection of available page sizes for the grid.
PagingModeGridPagingMode
Paged
Determines whether the grid uses traditional paging or infinite-scroll virtualisation.
PersistedRowsSnapshotPersistedGridRowsSnapshot?
Server-prerender → interactive handoff for the rendered page of rows. The framework auto-persists this property at the end of prerender and re-hydrates it before GridBase.OnInitializedAsync on the interactive side, so the data fetch can be skipped on first interactive render. Keyed by render-tree position by the framework; the PersistedGridRowsSnapshot.ViewId field is checked at consumption time so a rerender against a different view discards the stale rows. Public per the framework's requirement — [PersistentState] only sees public properties via reflection — but not intended to be set externally.
PersistedStateQueryParameterstring?
Name of the URL query-string parameter to persist the grid's interactive state to. When set, the grid reads this parameter on initial load and seeds the active view, page number, page size, and sort from it; subsequent user actions (view pick, page change, header sort, etc.) write the new state back via Components.NavigationManager's replace-state path. Persistence survives page refresh and bookmarks.
RecordTableRecord?
The parent record supplied via a cascading parameter; related records are filtered by this record's identity.
RelationshipName*string
The schema name of the relationship used to filter and display related records in this sub-grid.
SelectedRecordsIEnumerable<TableRecord>
Records that are currently selected in the Grid.
SelectFromEntireRowbool
True
When true, clicking anywhere on a row selects it; when false, only the checkbox selects the row.
SelectModeDataGridSelectMode
Multiple
Controls whether the grid allows single or multiple row selection.
Titlestring?
Name to display when the view dropdown is not displayed.
TransformViewAsyncFunc<GridViewDefinition, Task<GridViewDefinition>>?
Optional callback that runs immediately after a view is loaded and before the grid uses it to build columns or queries. Return a modified Models.GridViewDefinition to transform what the grid ultimately renders — for example, to ensure a specific column is always present regardless of the view's own configuration. Async so callers can consult metadata caches, services, or other async resources while deciding what to include.
ViewIdsIEnumerable<Guid>?
List of id's of the views that the grid should limit to in the view dropdown.
ViewSortViewSort
NameAscending
Sort order of the views in the view dropdown.
Name: AllowChangingPageSize
Type: bool
Default: True
Description: When true, the user can change the number of items displayed per page.
Name: AllowDownloadForFileColumns
Type: bool
Default: True
Description: When true (the default), the grid renders a per-row download icon at the trailing edge of file and image column cells. Clicking it streams the file to the user's browser. Set to false to suppress the icon — for example on read-only audit grids where file export isn't allowed.
Name: AllowEdit
Type: bool
Default: False
Description: Should the option be available for the user to turn on inline editing for the grid.
Name: AllowNavigateOnPrimaryNameClick
Type: bool
Default: True
Description: When true (the default) and the grid has a registered 'edit' button (a GridButton with IsOpenRecordButton=true), the cell that renders the table's primary-name column becomes a hyperlink. Clicking it dispatches the same per-row invocation that a row double-click would — so a user can jump to the edit form (or the navigated edit URL, depending on the registered button) without first selecting the row. Set to false to suppress the hyperlink and render the primary-name cell as plain text. Has no effect when no edit button is registered.
Name: AllowNavigateOnRowDoubleClick
Type: bool
Default: True
Description: When true (the default) and the grid has a registered 'edit' button (a GridButton with IsOpenRecordButton=true), double-clicking a row invokes that button's OnClick for the row's record — opening the edit dialog or navigating to the edit URL, whichever the button does. Set to false to suppress the double-click handler. Has no effect when no edit button is registered.
Name: AllowPreviewForFileColumns
Type: bool
Default: True
Description: When true (the default), the grid renders a per-row 'eye' preview icon at the trailing edge of file and image column cells whose contents can be rendered inline (images, PDFs, plain text). Set to false to suppress the icon — for example on grids where the columns shouldn't double as a preview entry point.
Name: AllowSearch
Type: bool
Default: True
Description: Should the user be allowed to search the grid.
Name: BorderVisible
Type: bool
Default: True
Description: Controls whether a visible border is rendered around the grid.
Name: Buttons
Type: RenderFragment?
Description: Optional render fragment used to define the button toolbar displayed above the grid.
Name: Columns
Type: RenderFragment?
Description: Optional Components.GridColumns fragment carrying consumer-declared Components.GridColumn children. When supplied, the grid switches to replace mode: only the declared columns render (in declared order), the FetchXML projection is rewritten to match, and the underlying view's column list is ignored. null leaves the grid in its default behavior (auto-generate columns from the view's resolved column set).
Name: CustomViewDefinitions
Type: List<GridViewDefinition>?
Description: Custom views to display in the dropdown.
Name: DataSource
Type: ViewDataSource?
Description: Optional shared Data.ViewDataSource. When set, the grid reads its rows + total count from the datasource instead of issuing its own RetrieveRecordsAsync(System.String) call — the same datasource can drive a sibling <DataverseChart> or a second grid so they all paginate / filter / search together off one round-trip. Standalone usage (no GridBase.DataSource) keeps the existing internal-state machine — the grid composes FetchXML and fetches via IPowerPortalsProService directly. What the datasource does NOT own: per-grid UI state (selected rows, pending row creates / updates / deletes, column widths). Those stay grid-local — two grids sharing one datasource can still have independent selection and per-grid pending edits. When ViewDataSource.Highlight is set (e.g. via a chart slice click in cross-filter 'highlight' mode), rows whose value in the highlighted column doesn't match are visually muted via a CSS class; the row data + selection are unaffected (the soft cross-filter is purely styling).
Name: DefaultItemsPerPage
Type: int
Default: 50
Description: Default number of records to load on a page.
Name: DefaultViewId
Type: Guid?
Description: Id of the view that the grid should display upon initial load.
Name: Editable
Type: bool
Default: False
Description: Is inline editing turned on for the grid.
Name: Filters
Type: IReadOnlyList<GridFilterBase>?
Description: Additional server-side filters AND-merged onto the resolved view's FetchXML before paging / sorting / searching kick in. Forwarded to Query.IFetchXmlQueryComposer's FetchXmlQueryOptions.Filters, so each entry is dispatched by runtime type (e.g. Models.RelationshipFilter AND-merges a relationship link-entity). Typical use: the LinkExistingRecordGridButton picker passes a Models.RelationshipFilter with RelationshipFilterMode.ExcludeExistingRecords so already- linked records are hidden from the M2M lookup dialog. Combines additively with SubGrid's own internal relationship filter (which is built into the FetchXML directly rather than going through the composer's Filters slot) — both end up in the same query.
Name: FullSize
Type: bool
Default: False
Description: When true, the grid expands to fill all available vertical space instead of using a fixed minimum height.
Name: HidePaging
Type: bool
Default: False
Description: Force the page size and paging components to be hidden. Only do this when the number of items is known and the page size is set to something greater than the item count.
Name: IncludeSearchInPersistedState
Type: bool
Default: False
Description: When true, the active search text is included in the persisted state URL parameter (under the q field). Defaults to false — search terms can be sensitive, accumulate in browser history, and leak into HTTP referrers, so the grid keeps them out of the URL unless the consumer explicitly opts in. Has no effect when GridBase.PersistedStateQueryParameter is not set.
Name: IsDirty
Type: bool
Default: False
Description: Indicates whether the grid has unsaved create, update, or delete operations pending.
Name: LoadedRecords
Type: IEnumerable<TableRecord>
Description: Records currently rendered in the grid (the most recent page of results). Intended for toolbar commands that need to act on 'everything shown' — e.g. a bulk download button. Does not span pages; bulk-across-pages operations should run their own unpaged fetch instead.
Name: MaxHeight
Type: string?
Description: Max Height that the grid control should expand to.
Name: MinHeight
Type: string?
Default: 300px
Description: Minimum height that the grid control should occupy.
Name: Mode
Type: GridMode
Default: RecordSelection
Description: Sets the behavioural mode of the grid, such as default interaction or record-selection mode.
Name: PageSizes
Type: IEnumerable<int>
Description: Collection of available page sizes for the grid.
Name: PagingMode
Type: GridPagingMode
Default: Paged
Description: Determines whether the grid uses traditional paging or infinite-scroll virtualisation.
Name: PersistedRowsSnapshot
Type: PersistedGridRowsSnapshot?
Description: Server-prerender → interactive handoff for the rendered page of rows. The framework auto-persists this property at the end of prerender and re-hydrates it before GridBase.OnInitializedAsync on the interactive side, so the data fetch can be skipped on first interactive render. Keyed by render-tree position by the framework; the PersistedGridRowsSnapshot.ViewId field is checked at consumption time so a rerender against a different view discards the stale rows. Public per the framework's requirement — [PersistentState] only sees public properties via reflection — but not intended to be set externally.
Name: PersistedStateQueryParameter
Type: string?
Description: Name of the URL query-string parameter to persist the grid's interactive state to. When set, the grid reads this parameter on initial load and seeds the active view, page number, page size, and sort from it; subsequent user actions (view pick, page change, header sort, etc.) write the new state back via Components.NavigationManager's replace-state path. Persistence survives page refresh and bookmarks.
Name: Record
Type: TableRecord?
Description: The parent record supplied via a cascading parameter; related records are filtered by this record's identity.
Name: RelationshipName*
Type: string
Description: The schema name of the relationship used to filter and display related records in this sub-grid.
Name: SelectedRecords
Type: IEnumerable<TableRecord>
Description: Records that are currently selected in the Grid.
Name: SelectFromEntireRow
Type: bool
Default: True
Description: When true, clicking anywhere on a row selects it; when false, only the checkbox selects the row.
Name: SelectMode
Type: DataGridSelectMode
Default: Multiple
Description: Controls whether the grid allows single or multiple row selection.
Name: Title
Type: string?
Description: Name to display when the view dropdown is not displayed.
Name: TransformViewAsync
Type: Func<GridViewDefinition, Task<GridViewDefinition>>?
Description: Optional callback that runs immediately after a view is loaded and before the grid uses it to build columns or queries. Return a modified Models.GridViewDefinition to transform what the grid ultimately renders — for example, to ensure a specific column is always present regardless of the view's own configuration. Async so callers can consult metadata caches, services, or other async resources while deciding what to include.
Name: ViewIds
Type: IEnumerable<Guid>?
Description: List of id's of the views that the grid should limit to in the view dropdown.
Name: ViewSort
Type: ViewSort
Default: NameAscending
Description: Sort order of the views in the view dropdown.

Events

Name
Type
Description
EditableChangedEventCallback<bool>
Callback invoked when the inline editing state changes.
SelectedRecordsChangedEventCallback<IEnumerable<TableRecord>>
Callback invoked when the selected records collection changes.
Name: EditableChanged
Type: EventCallback<bool>
Description: Callback invoked when the inline editing state changes.
Name: SelectedRecordsChanged
Type: EventCallback<IEnumerable<TableRecord>>
Description: Callback invoked when the selected records collection changes.

Methods

Name
Parameters
Type
Description
ClearSelectionAsyncTask
Clears all currently selected rows.
OpenFileDownloadAsyncTableRecord record
string columnName
Task
Fetches the file/image column's bytes for record and streams them to the user's browser as a download. Invoked by the per-row download icon in file and image cells.
OpenFilePreviewAsyncTableRecord record
string columnName
Task
Opens the inline preview dialog for the file/image column columnName on record. Invoked by the per-row preview icon in file/image cells and also available to composing components (for example, a toolbar button on a wrapping grid) that want a programmatic entry point.
RefreshAsyncbool forceRefresh
Task
Instructs the grid to re-fetch and render the current data from the supplied data source.
Validatebool
Validates all editable rows in the grid.
Name: ClearSelectionAsync
Type: Task
Description: Clears all currently selected rows.
Name: OpenFileDownloadAsync
Parameters: TableRecord record
string columnName
Type: Task
Description: Fetches the file/image column's bytes for record and streams them to the user's browser as a download. Invoked by the per-row download icon in file and image cells.
Name: OpenFilePreviewAsync
Parameters: TableRecord record
string columnName
Type: Task
Description: Opens the inline preview dialog for the file/image column columnName on record. Invoked by the per-row preview icon in file/image cells and also available to composing components (for example, a toolbar button on a wrapping grid) that want a programmatic entry point.
Name: RefreshAsync
Parameters: bool forceRefresh
Type: Task
Description: Instructs the grid to re-fetch and render the current data from the supplied data source.
Name: Validate
Type: bool
Description: Validates all editable rows in the grid.