HxGrid #

Grid to display tabular data from data source. Includes support for client-side and server-side paging & sorting (or virtualized scrolling as needed).

Basic usage #

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)
			};
	}
}

Note: The demos on this page use DemoDataService, in-memory simulation of a simple data store. Find the implementation on GitHub.

Automatic sorting and paging #

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.

Name
Phone
Salary
Position
Location

Using IQueryable #

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.

Name
Phone
Salary
Position
Location

Refreshing data #

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.

Name
Phone
Salary
Position
Location

Empty data #

When the DataProvider returns no data, the EmptyDataTemplate is rendered. If you do not set your own content, the <HxGridDefaultEmptyDataTemplateContent /> is used.

Name
Phone
Salary
Position
Location

Content navigation modes #

HxGrid offers various navigation modes, configurable through the ContentNavigationMode parameter. The default mode is set to Pagination.

Infinite scroll (virtualized) #

Enable continuous scrolling in HxGrid by setting ContentNavigationMode="GridContentNavigationMode.InfiniteScroll". This feature leverages the capabilities, requirements, and limitations of Blazor's Virtualize component.

Name
Phone
Salary
Position
Location

Load more button #

With ContentNavigationMode.LoadMore you can allow loading additional items with a Load more button.

Name
Phone
Salary
Position
Location

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.

Custom paging #

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.

Name
Phone
Salary
Position
Location

Context menu #

Add a context menu to the grid using HxContextMenuGridColumn. For additional information, refer to HxContextMenu.

Name
Phone
Salary
Position
Location

Multiselect with checkboxes #

Enable multi-row selection for users by setting MultiSelectionEnabled="true". The selected items can be accessed via the SelectedDataItems parameter, which is bindable.

Name
Phone
Salary
Position
Location

Selected employees:

Inline-editing #

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.

Name
Phone
Salary
Position
Location

Filtering from headers #

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.

Name
Phone
Salary
Position
Location

Hoverable rows #

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.

Name
Phone
Salary
Position
Location

Striped rows #

Use the Striped parameter to add zebra-striping, creating alternating row colors.

Name
Phone
Salary
Position
Location

Persisting the state #

Persist the grid state by loading or saving the CurrentUserState parameter. The GridUserState class is designed to be serializable.

Name
Phone
Salary
Position
Location

API #

Parameters #

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.

Methods #

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.

Static properties #

Property Type Description
Defaults GridSettings Application-wide defaults for the HxGrid and derived components.

CSS variables #

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)

HxGridColumn #

Grid column.

API #

Parameters #

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).

HxContextMenuGridColumn #

Column for displaying the HxContextMenu in the HxGrid.

API #

Parameters #

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).

HxGridEmptyDataTemplateDefaultContent #

API #

Parameters #

Name Type Description
ChildContent RenderFragment Content of the component.
An unhandled error has occurred. Reload 🗙