DataGrid

The DataGrid component is meant to emulate the asp:DataGrid control in markup and is defined in the System.Web.UI.WebControls.DataGrid class

Features supported in Blazor

• Readonly grid
• Bound, Button, Hyperlink, and Template columns
• Auto-generate columns
• Show/Hide header row
• Empty data text
• Paging (AllowPaging, PageSize, CurrentPageIndex, PageIndexChanged event)
• Sorting (AllowSorting, SortCommand event — sortable column headers)
• Selection (SelectedIndex, SelectedIndexChanged event)
• Editing (EditItemIndex — inline row editing support)
• Style sub-components (ItemStyle, AlternatingItemStyle, HeaderStyle, FooterStyle, PagerStyle, SelectedItemStyle, EditItemStyle)
• Caption property
• GridLines property (None, Horizontal, Vertical, Both)
• UseAccessibleHeader property (renders <th scope="col"> for accessibility)
• CellPadding and CellSpacing properties
• ShowFooter property
• ItemCreated / ItemDataBound events
• OnItemCommand, OnEditCommand, OnCancelCommand, OnUpdateCommand, OnDeleteCommand events

Blazor Notes

• The ItemCommand.CommandSource object will be populated with the ButtonField object
• DataGrid uses the same column types as GridView (BoundField, ButtonField, etc.)
• DataGrid is a legacy control superseded by GridView in ASP.NET 2.0, but is provided for compatibility
• ItemType cascading - The ItemType parameter is automatically cascaded from the DataGrid to child columns. You only need to specify it once on the DataGrid, and all child columns (BoundField, TemplateField, HyperLinkField, ButtonField) will automatically infer the type. For backward compatibility, you can still explicitly specify ItemType on individual columns if desired.

Web Forms Features NOT Supported

The following DataGrid features from Web Forms are not currently supported:

• Custom paging (AllowCustomPaging, VirtualItemCount)
• Footer templates

Web Forms Declarative Syntax

<asp:DataGrid
    AllowCustomPaging="True|False"
    AllowPaging="True|False"
    AllowSorting="True|False"
    AutoGenerateColumns="True|False"
    BackColor="color name|#dddddd"
    BackImageUrl="uri"
    BorderColor="color name|#dddddd"
    BorderStyle="NotSet|None|Dotted|Dashed|Solid|Double|Groove|Ridge|Inset|Outset"
    BorderWidth="size"
    CellPadding="integer"
    CellSpacing="integer"
    CssClass="string"
    CurrentPageIndex="integer"
    DataKeyField="string"
    DataMember="string"
    DataSource="string"
    DataSourceID="string"
    EditItemIndex="integer"
    EnableViewState="True|False"
    Font-Bold="True|False"
    Font-Italic="True|False"
    Font-Names="string"
    Font-Overline="True|False"
    Font-Size="string|Smaller|Larger|XX-Small|X-Small|Small|Medium|Large|X-Large|XX-Large"
    Font-Strikeout="True|False"
    Font-Underline="True|False"
    ForeColor="color name|#dddddd"
    GridLines="None|Horizontal|Vertical|Both"
    HeaderStyle-BackColor="color name|#dddddd"
    HeaderStyle-Font-Bold="True|False"
    HorizontalAlign="NotSet|Left|Center|Right|Justify"
    ID="string"
    OnCancelCommand="CancelCommand event handler"
    OnDataBinding="DataBinding event handler"
    OnDeleteCommand="DeleteCommand event handler"
    OnEditCommand="EditCommand event handler"
    OnItemCommand="ItemCommand event handler"
    OnItemCreated="ItemCreated event handler"
    OnItemDataBound="ItemDataBound event handler"
    OnPageIndexChanged="PageIndexChanged event handler"
    OnSortCommand="SortCommand event handler"
    OnUpdateCommand="UpdateCommand event handler"
    PageSize="integer"
    runat="server"
    SelectedIndex="integer"
    ShowFooter="True|False"
    ShowHeader="True|False"
    Visible="True|False"
>
    <AlternatingItemStyle />
    <Columns>
        <asp:BoundColumn
            DataField="string"
            DataFormatString="string"
            FooterText="string"
            HeaderImageUrl="uri"
            HeaderText="string"
            ReadOnly="True|False"
            SortExpression="string"
            Visible="True|False"
        >
            <FooterStyle />
            <HeaderStyle />
            <ItemStyle />
        </asp:BoundColumn>
        <asp:ButtonColumn
            ButtonType="LinkButton|PushButton"
            CausesValidation="True|False"
            CommandName="string"
            DataTextField="string"
            DataTextFormatString="string"
            FooterText="string"
            HeaderImageUrl="uri"
            HeaderText="string"
            SortExpression="string"
            Text="string"
            ValidationGroup="string"
            Visible="True|False"
        />
        <asp:HyperLinkColumn
            DataNavigateUrlField="string"
            DataNavigateUrlFormatString="string"
            DataTextField="string"
            DataTextFormatString="string"
            FooterText="string"
            HeaderImageUrl="uri"
            HeaderText="string"
            NavigateUrl="uri"
            SortExpression="string"
            Target="string"
            Text="string"
            Visible="True|False"
        />
        <asp:TemplateColumn
            FooterText="string"
            HeaderImageUrl="uri"
            HeaderText="string"
            SortExpression="string"
            Visible="True|False"
        >
            <EditItemTemplate>
                <!-- template content -->
            </EditItemTemplate>
            <FooterTemplate>
                <!-- template content -->
            </FooterTemplate>
            <HeaderTemplate>
                <!-- template content -->
            </HeaderTemplate>
            <ItemTemplate>
                <!-- template content -->
            </ItemTemplate>
        </asp:TemplateColumn>
    </Columns>
    <EditItemStyle />
    <FooterStyle />
    <HeaderStyle />
    <ItemStyle />
    <PagerStyle Mode="NextPrev|NumericPages" />
    <SelectedItemStyle />
</asp:DataGrid>

Blazor Syntax

<DataGrid
    AllowPaging=bool
    AllowSorting=bool
    AutoGenerateColumns=bool
    Caption=string
    CellPadding=int
    CellSpacing=int
    CssClass=string
    CurrentPageIndex=int
    DataKeyField=string
    DataSource=IEnumerable
    EditItemIndex=int
    EmptyDataText=string
    Enabled=bool
    GridLines=GridLines
    ID=string
    Items=IEnumerable
    ItemType=Type
    PageSize=int
    SelectedIndex=int
    OnDataBinding=EventCallBack
    OnDataBound=EventCallBack
    OnItemCommand=EventCallBack<DataGridCommandEventArgs>
    OnEditCommand=EventCallBack<DataGridCommandEventArgs>
    OnCancelCommand=EventCallBack<DataGridCommandEventArgs>
    OnUpdateCommand=EventCallBack<DataGridCommandEventArgs>
    OnDeleteCommand=EventCallBack<DataGridCommandEventArgs>
    ItemCreated=EventCallback<DataGridItemEventArgs>
    ItemDataBound=EventCallback<DataGridItemEventArgs>
    PageIndexChanged=EventCallback<DataGridPageChangedEventArgs>
    SortCommand=EventCallback<DataGridSortCommandEventArgs>
    SelectedIndexChanged=EventCallback
    OnInit=EventCallBack
    OnLoad=EventCallBack
    OnPreRender=EventCallBack
    OnUnload=EventCallBack
    OnDisposed=EventCallBack
    SelectMethod=SelectHandler
    ShowHeader=bool
    ShowFooter=bool
    TabIndex=int
    UseAccessibleHeader=bool
    Visible=bool
>
    <HeaderStyle BackColor=string ForeColor=string Font-Bold=bool ... />
    <ItemStyle BackColor=string ForeColor=string ... />
    <AlternatingItemStyle BackColor=string ForeColor=string ... />
    <FooterStyle BackColor=string ForeColor=string Font-Italic=bool ... />
    <PagerStyle BackColor=string ForeColor=string ... />
    <SelectedItemStyle BackColor=string ForeColor=string ... />
    <EditItemStyle BackColor=string ForeColor=string ... />
    <Columns>
        <BoundField
            DataField=string
            DataFormatString=string
            HeaderText=string
            Visible=bool
        />
        <HyperLinkField
            DataNavigateUrlFields=string
            DataNavigateUrlFormatString=string
            DataTextField=string
            DataTextFormatString=string
            HeaderText=string
            NavigateUrl=string
            Target=string
            Text=string
            Visible=bool
        />
        <ButtonField
            ButtonType=ButtonType
            CommandName=string
            DataTextField=string
            DataTextFormatString=string
            HeaderText=string
            ImageUrl=string
            Text=string
            Visible=bool
        />
        <TemplateField
            HeaderText=string
            Visible=bool
        >
            <ItemTemplate>
                <!-- template content -->
            </ItemTemplate>
        </TemplateField>
    </Columns>
</DataGrid>

Style Sub-Components

The DataGrid supports 7 style sub-components that control the appearance of different row types. Each is specified as a child element:

Style Component	Description
HeaderStyle	Styles the header row
FooterStyle	Styles the footer row
ItemStyle	Styles normal data rows
AlternatingItemStyle	Styles alternating data rows
PagerStyle	Styles the pager row
SelectedItemStyle	Styles the selected row
EditItemStyle	Styles the row being edited

Each style component accepts standard style properties: BackColor, ForeColor, CssClass, Font-Bold, Font-Italic, Font-Size, HorizontalAlign, VerticalAlign, Width, Height, etc.

Caption Property

The Caption property renders a <caption> element inside the <table>, providing an accessible description of the table's purpose.

GridLines Property

Controls which table borders are displayed using the HTML rules attribute:

Value	Description
GridLines.None	No grid lines
GridLines.Horizontal	Horizontal lines only
GridLines.Vertical	Vertical lines only
GridLines.Both	Both horizontal and vertical lines

UseAccessibleHeader Property

When true, header cells render as <th scope="col"> instead of <td>, improving accessibility for screen readers.

Migration Example

Before (Web Forms):

<asp:DataGrid ID="dgCustomers" runat="server"
    AutoGenerateColumns="False"
    GridLines="Both"
    Caption="Customer List">
    <HeaderStyle BackColor="#4472C4" ForeColor="White" Font-Bold="True" />
    <AlternatingItemStyle BackColor="#D6E4F0" />
    <Columns>
        <asp:BoundColumn DataField="CustomerID" HeaderText="ID" />
        <asp:BoundColumn DataField="CompanyName" HeaderText="Company" />
    </Columns>
</asp:DataGrid>

After (Blazor):

<DataGrid ItemType="Customer"
          AutoGenerateColumns="false"
          GridLines="GridLines.Both"
          Caption="Customer List"
          UseAccessibleHeader="true"
          SelectMethod="Customer.GetCustomers">
    <HeaderStyle BackColor="#4472C4" ForeColor="#FFFFFF" Font-Bold="true" />
    <AlternatingItemStyle BackColor="#D6E4F0" />
    <Columns>
        <BoundField DataField="CustomerID" HeaderText="ID" />
        <BoundField DataField="CompanyName" HeaderText="Company" />
    </Columns>
</DataGrid>

Examples

Basic DataGrid with Manual Columns

<DataGrid ItemType="Customer"
          AutoGenerateColumns="false"
          DataKeyField="CustomerID"
          SelectMethod="GetCustomers"
          EmptyDataText="No data available">
    <Columns>
        <BoundField ItemType="Customer" DataField="CustomerID" HeaderText="ID" />
        <BoundField ItemType="Customer" DataField="CompanyName" HeaderText="Company" />
        <BoundField ItemType="Customer" DataField="FirstName" HeaderText="First Name"/>
        <BoundField ItemType="Customer" DataField="LastName" HeaderText="Last Name"/>
    </Columns>
</DataGrid>

DataGrid with Auto-Generated Columns

<DataGrid ItemType="Customer"
          DataKeyField="CustomerID"
          SelectMethod="GetCustomers"
          AutoGenerateColumns="true">
</DataGrid>

DataGrid without Header

<DataGrid ItemType="Customer"
          AutoGenerateColumns="false"
          ShowHeader="false"
          SelectMethod="GetCustomers">
    <Columns>
        <BoundField ItemType="Customer" DataField="CustomerID" HeaderText="ID" />
        <BoundField ItemType="Customer" DataField="CompanyName" HeaderText="Company" />
    </Columns>
</DataGrid>

DataGrid with Paging

<DataGrid ItemType="Customer"
          AutoGenerateColumns="true"
          AllowPaging="true"
          PageSize="5"
          DataKeyField="CustomerID"
          SelectMethod="GetCustomers"
          PageIndexChanged="HandlePageChanged">
    <PagerStyle BackColor="#DDDDDD" ForeColor="#333333" />
</DataGrid>

@code {
    private void HandlePageChanged(DataGridPageChangedEventArgs e)
    {
        // e.NewPageIndex contains the new page index
    }
}

When AllowPaging="true" and PageSize is set, the DataGrid automatically renders a numeric pager row in the table footer. The pager displays page numbers — the current page as plain text, others as clickable links. Clicking a page number fires PageIndexChanged and navigates to that page.

DataGrid Paging vs. GridView/FormView/DetailsView Paging

DataGrid uses a built-in numeric pager and does not support the <PagerSettings> sub-component that GridView, FormView, and DetailsView use. If you need configurable pager modes (NextPrevious, NumericFirstLast, etc.), consider migrating to GridView which offers full PagerSettings support.

Property	Type	Default	Description
AllowPaging	bool	false	Enables or disables paging
PageSize	int	10	Number of items displayed per page
CurrentPageIndex	int	0	The zero-based index of the current page
PageIndexChanged	EventCallback<DataGridPageChangedEventArgs>	—	Fires when the page changes

The PagerStyle sub-component controls the visual appearance of the pager row.

DataGrid with Sorting

<DataGrid ItemType="Customer"
          AutoGenerateColumns="false"
          AllowSorting="true"
          SelectMethod="GetCustomers"
          SortCommand="HandleSort">
    <Columns>
        <BoundField DataField="CompanyName" HeaderText="Company" SortExpression="CompanyName" />
        <BoundField DataField="ContactName" HeaderText="Contact" SortExpression="ContactName" />
    </Columns>
</DataGrid>

@code {
    private void HandleSort(DataGridSortCommandEventArgs e)
    {
        // e.SortExpression contains the column's SortExpression value
        // Re-sort your data source and rebind
    }
}

Comparison with GridView

DataGrid and GridView are very similar in Blazor. The main differences are:

• DataGrid uses DataKeyField (singular) while GridView uses DataKeyNames
• DataGrid event names use "Item" (OnItemCommand) while GridView uses "Row" (OnRowCommand)
• DataGrid is a legacy control from ASP.NET 1.x, while GridView was introduced in ASP.NET 2.0
• For new projects, GridView is recommended as it has more features and better design-time support

Both controls use the same column types (BoundField, ButtonField, HyperLinkField, TemplateField) and render similar HTML.

Migration from Web Forms

When migrating DataGrid from Web Forms to Blazor:

1. Replace <asp:DataGrid> with <DataGrid>
2. Replace runat="server" (not needed in Blazor)
3. Change DataKeyNames to DataKeyField if using
4. Update event handler names (e.g., OnItemCommand instead of event code-behind)
5. Use SelectMethod instead of setting DataSource in code-behind
6. Consider migrating to GridView for better feature support

See Also

• GridView - The recommended data grid control for new projects
• DataList - For custom layout of repeating data
• Repeater - For lightweight data repetition
• PagerSettings - Shared pager configuration (used by GridView, FormView, DetailsView)