Components / Grid / Columns

New to Telerik UI for Blazor? Download free 30-day trial

Grid Data Bound Columns

This article explains the basics of showing data in a grid and the features of its bound columns.

Important related information are the Grid data binding fundamentals.

For details on Value Binding and Data Binding, and the differences between them, see the Value Binding vs Data Binding article.

Sections in this article:

Show Data In A Grid

To show data in a grid, you must define GridColumn instances in the GridColumns collection for the fields of the data source you want to show. Their Field parameter defines which property from the model is shown in the column. You can provide the collection of models to the grid in its Data parameter.

Provide data to the grid and choose which columns (fields) to see

@* define data, model and columns for a grid *@

@using System.ComponentModel.DataAnnotations
@* This Using is for the model class attributes only *@

<TelerikGrid Data="@MyData">
    <GridColumns>
        <GridColumn Field="@(nameof(SampleData.Id))" />
        <GridColumn Field="@(nameof(SampleData.Name))" />
        <GridColumn Field="@(nameof(SampleData.Team))" Title="Team" />
        <GridColumn Field="@(nameof(SampleData.HireDate))" Title="Hire Date" />
    </GridColumns>
</TelerikGrid>

@code {
    public IEnumerable<SampleData> MyData = Enumerable.Range(1, 30).Select(x => new SampleData
    {
        Id = x,
        Name = "name " + x,
        Team = "team " + x % 5,
        HireDate = DateTime.Now.AddDays(-x).Date
    });

    public class SampleData
    {
        public int Id { get; set; }
        [Display(Name = "Employee Name")]
        public string Name { get; set; }
        public string Team { get; set; }
        public DateTime HireDate { get; set; }
    }
}

You can also use a string for the field name, using the nameof operator is not necessary. For example, the ID column can be defined like this: <GridColumn Field="Id" />. The field name is, however, case-sensitive.

The Data collection can be an ObservableCollection, an array, a List - it must only implement IEnumerable.

Video tutorial - Get started with Telerik Data Grid for Blazor

Grid Bound Column Parameters

You can use the following properties on bound columns:

Data Binding

  • Field - (defaults to null) - the name of the field in the data source that the column will render as a string (case-sensitive). You can set its as a plain string (Field="SomeField") or to have .NET extract the field name from the model for flat models (Field=@nameof(MyModelClass.SomeFIeld)).
  • FieldType - when binding the grid to an object rather than a real model, set this to the typeof the field the column will be displaying. Such a case would be binding to expando objects, using OnRead with grouping or binding to a DataTable.

Appearance

  • Title - the text that is rendered in the column header. See the Notes below for its behavior.
  • DisplayFormat - the C# format string that is used to render the field value in the cell when the grid is in display mode. Read more in the Column Display Format article.
  • TextAlign - specifies the horizontal alignment of the data cells. For example, you can use this property to right-align numeric columns. The property accepts ColumnTextAlign enum values (Left, Right or Center). If not set, the text alignment will depend on existing styles on the page, default browser behavior and the text direction. Header cell alignment requires a different approach with HeaderClass and custom CSS - see Center Grid column header text.
  • OnCellRender - an event that fires upon the rendering of the Grids columns. For more information read the columns events article.
  • HeaderClass - string - adds a custom CSS class to the header cell of the column. Use it to apply custom styles or override the default Grid styles.
  • Reorderable - (defaults to true) - whether the user can drag to reorder this column.
  • Resizable - (defaults to true) - whether the user can resize this column.
  • Width - (defaults to null) - the width of the column. See the Dimensions article for information about the supported formats. See Grid Column Width Behavior for detailed information about the Grid behavior with different column width configurations.
  • MinResizableWidth - (defaults to 30 and ignores smaller values) - the minimum allowed column width during user resizing. Unlike the Width string property, this one is decimal and expects pixel values.
  • MaxResizableWidth - (defaults to 0) - the maximum allowed column width during user resizing. Unlike the Width string property, this one is decimal and expects pixel values.
  • Lockable - (defaults to true) - determines whether the user can pin the column through the column menu.
  • Locked - (defaults to false) - if this parameter is set to true it locks the column so it is always visible to the user.
  • Visible - (defaults to null) - if this parameter is set to false it hides the column from the Grid. Accepts both bool and bool? types, and null is treated like true.
  • Columns - a nested tag where you can declare multiple column headers.
  • ShowColumnMenu - (defaults to true) - if set to false, disables the column menu for that particular column.
  • VisibleInColumnChooser - (defaults to true) - if set to false, removes the column from the Column chooser of the column menu.

Identification

  • Id - a unique identifier of the Grid Column. Use to associate the column to the respective item in the column chooser when the columns are organized in sections.
  • ref - the standard Blazor reference name.

Data Operations

  • Editable - (defaults to true) - set it to true or false to allow or prevent editing of this field. To edit data, you also need a CommandColumn.
  • Filterable - (defaults to true) - set this to false so a filterable Grid will not let the user filter that particular column.
  • FilterEditorType - (defaults to GridFilterEditorType.DatePicker) - determines if the default filtering component of a DateTime column will be a DatePicker or a DateTimePicker.
  • FilterEditorFormat - sets the Format of the filtering component as a string. Works for DateTime and numeric columns. Do not use a placeholder (e.g. set "D", not "{0:D}").
  • Sortable - (defaults to true) - set it to false so the user cannot sort this column.
  • Groupable - (defaults to true) - whether the user can group the grid by this column.

Templates

  • Template - this property can also be used as an inner tag and it lets you define the column display content. It can also point to a component name.
  • Context - the standard Blazor context variable name for use inside the inline template.
  • EditorTemplate - this property can also be used as an inner tag and it lets you define the column edit content. It can also point to a component name.
  • FilterCellTemplate - this property can also be used as an inner tag and it lets you customize the Grid Filter Row. It can also point to a component name.
  • FilterMenuTemplate - this property can also be used as an inner tag and it lets you customize the Grid Filter Menu. It can also point to a component name.

You can find more examples in the rest of the grid documentation and in our live demos.

The Grid can automatically generate its columns out of the public properties of the model.

Notes

  • For advanced operations such as grouping, filtering, sorting, you must set a Field to the column, and the field it points to must be a string or a value type (such as a number, string, DateTime, boolean).

    • If a Field is not set the column will not allow filtering, grouping, sorting and editing for the column.
    • If the Field points to a custom object or something like an IDictionary, List, and Array errors will be thrown upon those actions because there are no known data operations for reference types in .NET, except for strings. To handle such scenarios you could flatten the collection and the underlying model.
    • To bind to nested (complex) models (also called navigation properties), use only the name of the field that holds the child class and its own field. For an example, see the Bind to navigation properties in complex objects article.

  • The Field of the column must point to a property in the model that has a public getter so that the grid can display data. For editing to be enabled, the property must have a public setter. For example:

    C# public class MyModel { public int WorkinProperty { get; set; } // has public getter and setter so it can be shown and edited public int NonWorkingField // no public getter, so the grid cannot display this }

  • Foreign Keys - using foreign tables and keys is usually done through the grid templates. You can read more and find examples in the Grid - Foreign Key KnowledgeBase article.

  • The grid skips fields marked with the IgnoreDataMemberAttribute when performing CUD operations. Its presence indicates that this property does not need to be part of the serialized data anyway, and skipping such fields allows Lazy Loading Proxies in EF to work.

  • If you don't set a Title for a column, the grid will take the [Display(Name = "My Column Title")] data annotation attribute from the model field. If that's not available either, the name of the field will be shown.

  • If the model has a [DisplayFormat(DataFormatString = "{0:C}")] data annotation attribute, the display format will be taken from the format string in the attribute.

  • If you want to prevent data mutation for a specific property you can set the Editable parameter of the GridColumn or the [Editable] data annotation attribute to false for the desired model field.

    • Columns generated out of model properties that do not have a setter or it is not accessible (private) will not be editable too.

  • The Grid uses Activator.CreateInstance<TItem>(); to generate a new item when an Insert action is invoked, so the Model should have a Parameterless constructor defined. A workaround might be invoking Insert through the grid state and creating the object with your own code.

  • The Data collection of the grid must contain instances of only one model type. You cannot bind the grid to a base class and populate its data with instances of inherited classes (neither one, nor more than one type) - extra fields from such inherited classes may not work or may even throw exceptions because the grid will not know about them when its Data collection is of the base class type.

You can optimize database queries in two ways:

  • Use an IQueryable<MyModel> collection for the grid Data. The grid will build a LINQ expression internally that will be resolved only when needed. This can be useful when the Data comes from something like an EntityFramework context.
  • Implement manual data source operations and implement the desired query yourself.

See Also

In this article
Related articles
Not finding the help you need? Improve this article