Grid to display tabular data from data source. Includes support for client-side and server-side paging & sorting (or virtualized scrolling as needed).
To define columns, use the HxGridColumn
components.
You can specify the HeaderText
and ItemTextSelector
parameters.
To connect the grid to your data, implement the DataProvider
method.
This method receives a "request" (for sorting and paging requirements) and yields a "result" (items for display along with the total item count).
Name | Phone | Salary | Position | Location |
---|---|---|---|---|
@inject IDemoDataService DemoDataService
<HxGrid TItem="EmployeeDto" DataProvider="GetGridData" PageSize="5" Responsive="true">
<Columns>
<HxGridColumn HeaderText="Name" ItemTextSelector="employee => employee.Name" />
<HxGridColumn HeaderText="Phone" ItemTextSelector="employee => employee.Phone" />
<HxGridColumn HeaderText="Salary" ItemTextSelector="@(employee => employee.Salary.ToString("c0"))" ItemCssClass="text-end" HeaderCssClass="text-end" />
<HxGridColumn HeaderText="Position" ItemTextSelector="employee => employee.Position" />
<HxGridColumn HeaderText="Location" ItemTextSelector="employee => employee.Location" />
</Columns>
</HxGrid>
@code {
private async Task<GridDataProviderResult<EmployeeDto>> GetGridData(GridDataProviderRequest<EmployeeDto> request)
{
// you usually pass the data-request to your API/DataLayer
return new GridDataProviderResult<EmployeeDto>()
{
Data = await DemoDataService.GetEmployeesDataFragmentAsync(request.StartIndex, request.Count, request.CancellationToken),
TotalCount = await DemoDataService.GetEmployeesCountAsync(request.CancellationToken)
};
}
}
HxGrid.DataProvider
should always return
an instance of GridDataProviderResult
, null
is not allowed.
The method you provide should be async
and should
await
the data if needed (loading progress is indicated in the meantime).
Note: The demos on this page use DemoDataService
, in-memory simulation of a simple data store.
Find the implementation on GitHub.
If you have your IEnumerable
data-source ready (all items preloaded in memory),
you can use the request.ApplyTo(data)
extension method to apply sorting and paging automatically.
When utilizing IQueryable
as your data source provider, commonly seen in Blazor Server applications,
you can employ the data.ApplyGridDataProviderRequest(request)
method.
This method enables the application of sorting and paging to your data source.
Subsequently, you are required to "execute" the queries independently.
This necessity arises because our components lack access to cancellable asynchronous methods
such as CountAsync
and ToListAsync
.
Employing cancellable methods is particularly critical in scenarios like infinite scrolling.
To refresh data in the grid, such as when there's a change in the filter being applied,
use the gridComponent.RefreshDataAsync()
method.
This action informs the grid to request updated data from the DataProvider
.
When the DataProvider
returns no data, the EmptyDataTemplate
is rendered.
If you do not set your own content, the <HxGridDefaultEmptyDataTemplateContent />
is used.
HxGrid
offers various navigation modes, configurable through the ContentNavigationMode
parameter.
The default mode is set to Pagination
.
Enable continuous scrolling in HxGrid
by setting ContentNavigationMode="GridContentNavigationMode.InfiniteScroll"
.
This feature leverages the capabilities, requirements, and limitations of Blazor's
Virtualize component.
ItemRowHeight
for effective virtualization. By default, it is 41 pixels, aligning with the standard table row height in Bootstrap.
With ContentNavigationMode.LoadMore
you can allow loading additional items with a Load more button.
Customize the button text using LoadMoreButtonText
, or design your own navigation interface with LoadMoreTemplate
.
This customization can be achieved using the context.LoadMoreAsync()
method.
It's also possible to combine the Load More button with pagination by opting for GridContentNavigationMode.PaginationAndLoadMore
.
HxGrid
uses the HxPager
to display pagination, unless a value for the PaginationTemplate
parameter is provided.
Context information is provided via GridPaginationTemplateContext
to your pager.
Add a context menu to the grid using HxContextMenuGridColumn
.
For additional information, refer to HxContextMenu.
Enable multi-row selection for users by setting MultiSelectionEnabled="true"
.
The selected items can be accessed via the SelectedDataItems
parameter, which is bindable.
SelectedDataItems
only includes visible items.
Items are removed from the selection when they become unrendered (for example, after paging, sorting, etc.).
Additionally, MultiSelectionEnabled
is not compatible
with InfiniteScroll
.
To enable inline editing, utilize the SelectedDataItem
and create an editing interface for such items.
This can be accomplished by defining the content of the ItemTemplate
within HxGridColumn
.
Use the SelectedDataItemChanged
event to save modifications,
or alternatively, include a column with command buttons for this purpose.
Set up filtering for individual columns by integrating your filtering interface
into the HeaderTemplate
of each column.
Then, apply the filters to the data within the DataProvider
based on the input values.
The Hover
parameter allows you to enable or disable the hover state on rows.
By default, the hover state is active when the grid's item selection feature is enabled, unless otherwise specified.
Use the Striped
parameter to add zebra-striping, creating alternating row colors.
Persist the grid state by loading or saving the CurrentUserState
parameter.
The GridUserState
class is designed to be serializable.
HxGridColumn<TItem>.Id
properties.
Name | Type | Description |
---|---|---|
ColumnsREQUIRED | RenderFragment |
Grid columns. |
DataProviderREQUIRED | GridDataProviderDelegate<TItem> |
Data provider delegate for the grid. The data provider is responsible for fetching items to be rendered in the grid.
It must always return an instance of GridDataProviderResult and cannot return null. |
ContentNavigationMode | GridContentNavigationMode? |
The strategy for how data items are displayed and loaded into the grid. Supported modes include pagination, load more, and infinite scroll. |
CurrentUserState | GridUserState |
Gets or sets the current state of the grid, including pagination and sorting information. This state can be used to restore the grid to a specific configuration or to synchronize it with external state management systems. |
CurrentUserStateChanged | EventCallback<GridUserState> |
Event that fires when the CurrentUserState property changes. This event can be used to react to changes in the grid's state, such as sorting or pagination adjustments. |
EmptyDataTemplate | RenderFragment |
Template for rendering when the data source is empty but not null. |
FooterRowCssClass | string |
A custom CSS class for the footer tr element in the grid. This allows styling of the grid footer independently of other grid elements. |
HeaderRowCssClass | string |
Custom CSS class for the header tr element in the grid. Enables specific styling for the header row separate from the rest of the grid. |
Hover | bool? |
Enables or disables the hover state on table rows within a <tbody> .
When not set, the table is hoverable by default if selection is enabled. This property customizes the hover behavior of the grid rows. |
InProgress | bool? |
Gets or sets a value indicating whether the grid is currently processing data, such as loading or refreshing items.
When set to null , the progress state is automatically managed based on the data provider's activity. |
ItemKeySelector | Func<TItem, object> |
Optionally defines a value for @key on each rendered row. Typically this should be used to specify a unique identifier, such as a primary key value, for each data item. This allows the grid to preserve the association between row elements and data items based on their unique identifiers, even when the TGridItem instances are replaced by new copies (for example, after a new query against the underlying data store). If not set, the @key will be the TItem instance itself. |
ItemRowCssClass | string |
Custom CSS class for the data tr elements in the grid. This class is applied to each row of data, providing a way to customize the styling of data rows. |
ItemRowCssClassSelector | Func<TItem, string> |
Function that defines a custom CSS class for each data tr element based on the item it represents.
This allows for conditional styling of rows based on their data. |
ItemRowHeight | float? |
Height of each item row, used primarily in calculations for infinite scrolling. The default value (41px) corresponds to the typical row height in the Bootstrap 5 default theme. |
LoadingDataTemplate | RenderFragment |
Defines a template for the initial data loading phase. This template is not used when loading data for sorting or paging operations. |
LoadMoreButtonSettings | ButtonSettings |
Configuration for the "Load more" button, including appearance and behavior settings. Relevant in grid modes that use a "Load more" button for data navigation. |
LoadMoreButtonText | string |
The text for the "Load more" button, used in the GridContentNavigationMode.LoadMore navigation mode. The default text is obtained from localization resources. |
LoadMoreTemplate | RenderFragment<GridLoadMoreTemplateContext> |
Template for the "load more" button (or other UI element). |
MultiSelectionEnabled | bool |
Enables or disables multi-item selection using checkboxes in the first column.
Can be used with single selection.
Defaults to false . |
OverscanCount | int? |
Defines the number of additional items to be rendered before and after the visible region in an infinite scrolling scenario. This helps to reduce the frequency of rendering during scrolling, though higher values increase the number of elements present in the page. Default is 3. |
PagerSettings | PagerSettings |
Pager settings. |
PageSize | int? |
The number of items to display per page. Applicable for grid modes such as pagination and load more. Set to 0 to disable paging. |
PaginationTemplate | RenderFragment<GridPaginationTemplateContext> |
Template for rendering custom pagination. |
PlaceholdersRowCount | int? |
The number of placeholder rows to be rendered in the grid. Placeholders are used when loading data or when LoadingDataTemplate
is not set. Set to 0 to disable placeholders. Default value is 5. |
ProgressIndicatorDelay | int? |
Delay in milliseconds before the progress indicator is displayed. The default value is 300 ms . |
Responsive | bool? |
Determines if the grid should be scrollable horizontally across different breakpoints.
When set to true, the table-responsive class is added to the table.
Default is false. |
SelectedDataItem | TItem |
Represents the currently selected data item in the grid for data binding and state synchronization. Changes trigger SelectedDataItemChanged . |
SelectedDataItemChanged | EventCallback<TItem> |
Event that fires when the SelectedDataItem property changes. This event is intended for data binding and state synchronization. |
SelectedDataItems | HashSet<TItem> |
Represents the collection of currently selected data items in the grid, primarily for data binding and state management in multi-selection scenarios. |
SelectedDataItemsChanged | EventCallback<HashSet<TItem>> |
Event that fires when the collection of selected data items changes. This is particularly relevant in multi-selection scenarios. It is intended for data binding and state synchronization. |
SelectionEnabled | bool |
Enables or disables single item selection by row click. Can be used alongside multi-selection.
Defaults to true . |
Settings | GridSettings |
Specifies the grid settings. Overrides default settings in Defaults and can be further overridden by individual parameters. |
ShowFooterWhenEmptyData | bool? |
Determines whether the grid footer is rendered when the grid's data source is empty. The default value is false . |
SortAscendingIcon | IconBase |
Icon to indicate the ascending sort direction in the column header. This icon is displayed when a column is sorted in ascending order. |
SortDescendingIcon | IconBase |
Icon to indicate the descending sort direction in the column header. This icon is shown when a column is sorted in descending order. |
Striped | bool? |
Adds zebra-striping to any table row within the <tbody> for better readability.
Rows will have alternating background colors.
Default is false. |
TableContainerCssClass | string |
Custom CSS class for the div element that wraps the main table element. Excludes the HxPager which is not wrapped in this div element. |
TableCssClass | string |
Custom CSS class for the main table element of the grid. This class allows for styling and customization of the grid's appearance. |
TableHeaderCssClass | string |
Custom CSS class for the thead element of the grid. This class allows for styling and customization of the grid's appearance. |
Method | Returns | Description |
---|---|---|
PagerCurrentPageIndexChanged(int newPageIndex) | Task |
|
RefreshDataAsync() | Task |
Requests a data refresh from the HxGrid.DataProvider .
Useful for updating the grid when 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-secondary-bg) |
--hx-grid-button-border-radius | Grid button border radius. | .25rem |
--hx-grid-sorted-icon-color | Color of the sorted icon. | var(--bs-primary) |
--hx-grid-progress-indicator-color | Color of the grid progress indicator line. | 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 that 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 a string. Used to set sorting as a string, i.e., to get value to pass to the 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 the item CSS class (not dependent on data). |
ItemCssClassSelector | Func<TItem, string> |
Returns the item CSS class for the specific data 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. |