Grid to display tabular data from data source. Includes support for client-side and server-side paging & sorting (or virtualized scrolling as needed).
Implement the DataProvider
method which is provided with a "request"
(requested sorting and paging) and returns a "result" (items to display and total count of items).
If you have your IEnumerable
data-source ready (all items), you can use the request.ApplyTo(data)
extension method to apply sorting and paging automatically.
If you have IQueryable
as a data-source provider, you can use the data.ApplyGridDataProviderRequest(request)
method to apply sorting and paging to your data source. Then you must query data on your own, because we do not have access to cancellable async methods
in the components (CountAsync, ToListAsync) and it is quite crutial to use cancellable methods, mainly for infinite scroll.
HxGrid.DataProvider
should always return an instance of GridDataProviderResult
, null
is not allowed.
The method you provide is async
and should await
the data if needed (loading progress is indicated in meantime).
Whenever you need to refresh data in the grid (e.g. when the filter to be applied changes),
call the gridComponent.RefreshDataAsync()
method to let the grid know
it should ask the DataProvider
for fresh data.
When the DataProvider
returns no data, the EmptyDataTemplate
is rendered (when not set, the <HxGridDefaultEmptyDataTemplateContent />
is used).
HxGrid
has several navigation modes, which can be set using the ContentNavigationMode
parameter.
The default navigation mode is Pagination
.
You can switch from paging to infinite-scroll by setting ContentNavigationMode="GridContentNavigationMode.InfiniteScroll"
.
Use a Placeholder (<Placeholder>...</Placeholder>
) to display content until the item data is available.
ItemRowHeight
parameter should be set for the virtualization to work properly. The default value is 41 pixels (default table row height in Bootstrap).
With ContentNavigationMode.LoadMore
you can allow loading additional items with a Load more button.
Button text can be customized with LoadMoreButtonText
or you can create your own navigation with
LoadMoreTemplate
(with help of the context.LoadMoreAsync()
method).
You can combine Load more button with pagination by using GridContentNavigationMode.PaginationAndLoadMore
.
Use HxContextMenuGridColumn
to add context-menu to the grid.
ContextMenu
parameter does the same (but renders always as last column) and will be most likely removed in vNext.You can let the user select multiple rows with MultiSelectionEnabled="true"
, selected items are represented by SelectedDataItems
parameter (bindable).
SelectedDataItems
contains only visible items. Items are removed from the selection if they are not rendered (e.g. after paging, sorting, ...).
MultiSelectionEnabled
cannot be combined with InfiniteScroll
.
To achieve an inline-editing experience, you can use the SelectedDataItem
and render editing UI for such items. Simply specify the content of the ItemTemplate
in HxGridColumn
and use the SelectedDataItemChanged
event to save changes (or you can add a column with command buttons).
Individual column filtering can be set up by adding your filtering UI to the columns' HeaderTemplate
s and filtering the data in the DataProvider
based on the values provided.
You can set Hover
parameter to enable/disable hover state on rows. If not set, hover state is enabled if the grid has selection enabled.
You can set Striped
parameter to adds zebra-striping (alternating rows).
You can load/save CurrentUserState
parameter to persist the grid state.
HxGridColumn<TItem>.Id
properties.
Name | Type | Description |
---|---|---|
ColumnsREQUIRED | RenderFragment |
Columns template. |
DataProviderREQUIRED | GridDataProviderDelegate<TItem> |
Data provider for items to render. The provider should always return instance of GridDataProviderResult , null is not allowed. |
ContentNavigationMode | GridContentNavigationMode? |
Strategy how data are displayed in the grid (and loaded to the grid). |
ContextMenu | RenderFragment<TItem> |
Context menu template (positioned as last column). NOTE: This parameter will be most likely removed in vNext, use HxContextMenuGridColumn in Columns instead. |
CurrentUserState | GridUserState |
Current grid state (page, sorting). |
CurrentUserStateChanged | EventCallback<GridUserState> |
Event fires when grid state is changed. |
EmptyDataTemplate | RenderFragment |
Template to render when there is empty Data (but not null ). |
FooterRowCssClass | string |
Custom CSS class to render with footer tr element. |
HeaderRowCssClass | string |
Custom CSS class to render with header tr element. |
Hover | bool? |
Enables hover state on table rows within a <tbody> (sets the table-hover class on the table).If not set (default) the table is hoverable when selection is enabled. |
InProgress | bool? |
Indicates when the grid should be displayed as "in progress".
When not set (null ), grid progress is automatically tracked when retrieving data by data provider. |
ItemRowCssClass | string |
Custom CSS class to render with data tr element. |
ItemRowCssClassSelector | Func<TItem, string> |
Returns custom CSS class to render with data tr element. |
ItemRowHeight | float? |
Height of the item row used for infinite scroll calculations.
Default value is 41px (row-height of regular table-row within Bootstrap 5 default theme). |
LoadingDataTemplate | RenderFragment |
Template to render when "first" data are loading. This template is not used when loading data for sorting or paging operations. |
LoadMoreButtonSettings | ButtonSettings |
Settings for the "Load more" navigation button (GridContentNavigationMode.LoadMore ). |
LoadMoreButtonText | string |
Text of the "Load more" navigation button (GridContentNavigationMode.LoadMore ).
(Default is taken from the localization resources.) |
LoadMoreTemplate | RenderFragment<GridLoadMoreTemplateContext> |
Template to render "load more" button (or other UI element). |
MultiSelectionEnabled | bool |
Indicates whether multi data items selection is enabled.
Selection is performed by checkboxes in the first column.
Can be combined with (single) selection.
Default is false . |
OverscanCount | int? |
Infinite scroll:
Gets or sets a value that determines how many additional items will be rendered
before and after the visible region. This help to reduce the frequency of rendering
during scrolling. However, higher values mean that more elements will be present
in the page. Default is 50 . |
PagerSettings | PagerSettings |
Pager settings. |
PageSize | int? |
Page size for GridContentNavigationMode.Pagination , GridContentNavigationMode.LoadMore and GridContentNavigationMode.PaginationAndLoadMore . Set 0 to disable paging. |
PlaceholdersRowCount | int? |
Number of rows with placeholders to render.
When value is zero, placeholders are not used.
When LoadingDataTemplate is set, placeholder are not used.
Default is 5 . |
Responsive | bool? |
Allows the table to be scrolled horizontally with ease across any breakpoint (adds the table-responsive class to the table).Default is false . |
SelectedDataItem | TItem |
Selected data item. Intended for data binding. |
SelectedDataItemChanged | EventCallback<TItem> |
Event fires when selected data item changes. Intended for data binding. |
SelectedDataItems | HashSet<TItem> |
Selected data items. Intended for data binding. |
SelectedDataItemsChanged | EventCallback<HashSet<TItem>> |
Event fires when selected data items changes. Intended for data binding. |
SelectionEnabled | bool |
Indicates whether single data item selection is enabled.
Selection is performed by click on the item row.
Can be combined with multiselection.
Default is true . |
Settings | GridSettings |
Set of settings to be applied to the component instance (overrides HxGrid.Defaults , overridden by individual parameters). |
ShowFooterWhenEmptyData | bool? |
Indicates whether to render footer when data are empty.
Default is false . |
SortAscendingIcon | IconBase |
Icon to indicate ascending sort direction in column header. |
SortDescendingIcon | IconBase |
Icon to indicate descending sort direction in column header. |
Striped | bool? |
Adds zebra-striping to any table row within the <tbody> (alternating rows).Default is false . |
TableContainerCssClass | string |
Custom CSS class to render with div element wrapping the main table (HxPager is not wrapped in this div element). |
TableCssClass | string |
Custom CSS class to render with main table element. |
Method | Returns | Description |
---|---|---|
RefreshDataAsync() | Task |
Instructs the component to re-request data from its HxGrid.DataProvider .
This is useful if external data may have changed. |
Property | Type | Description |
---|---|---|
Defaults | GridSettings |
Application-wide defaults for the HxGrid and derived components. |
Name | Description | Default |
---|---|---|
--hx-grid-button-hover-background | Grid button background color on hover. | var(--bs-gray-300) |
--hx-grid-button-border-radius | Grid button border radius. | .25rem |
--hx-grid-sorted-icon-color | Color of the sorted icon. | var(--bs-primary) |
Grid column.
Name | Type | Description |
---|---|---|
FooterCssClass | string |
Footer cell css class. |
FooterTemplate | RenderFragment<GridFooterCellContext> |
Footer cell template. |
FooterText | string |
Footer cell text. |
HeaderCssClass | string |
Header cell css class. |
HeaderTemplate | RenderFragment<GridHeaderCellContext> |
Header cell template. |
HeaderText | string |
Header cell text. |
Id | string |
Column unique identifier. |
IsDefaultSortColumn | bool |
Indicates the sorting on the column is default (primary) on the grid.
Set true for the column which is to be used for default sorting. |
ItemCssClass | string |
Returns item css class (not dependent on data). |
ItemCssClassSelector | Func<TItem, string> |
Returns item css class for the specific date item. |
ItemTemplate | RenderFragment<TItem> |
Returns template for the item. |
ItemTextSelector | Func<TItem, string> |
Returns text for the item. |
Order | int |
The order (display index) of the column. Columns are displayed in the order of this property. Columns with the same value are displayed in the order of appearance in the code (when the columns are not conditionally displayed using @if). |
PlaceholderTemplate | RenderFragment<GridPlaceholderCellContext> |
Placeholder cell template. |
SortDirection | SortDirection |
Initial sorting direction. Default is SortDirection.Ascending . |
SortKeySelector | Expression<Func<TItem, IComparable>> |
Returns column sorting expression for automatic grid sorting.
To be used for "strongly typed" setting of sorting, required for client-side sorting.
Must be IComparable .
Sorting of the column does not support multiple expressions. Create an artificial property and implement IComparable . |
SortString | string |
Returns column sorting as string. Use to set sorting as a string, ie. to get value to pass to backend. Ignored for client-side sorting. |
Visible | bool |
Indicates whether the column is visible (otherwise the column is hidden). |
Column for displaying the HxContextMenu
in the HxGrid
.
Name | Type | Description |
---|---|---|
ChildContent | RenderFragment<TItem> |
Context menu template. |
ItemCssClass | string |
Returns item css class (not dependent on data). |
ItemCssClassSelector | Func<TItem, string> |
Returns item css class for the specific date item. |
Order | int |
The order (display index) of the column. Columns are displayed in the order of this property. Columns with the same value are displayed in the order of appearance in the code (when the columns are not conditionally displayed using @if). |
Name | Type | Description |
---|---|---|
ChildContent | RenderFragment |
Content of the component. |