# Data Binding Overview

This article describes the fundamentals of data binding the Telerik Blazor components.

* [Value Binding vs Data Binding](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#data-binding-vs-value-binding)
* [Data binding options](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#how-to-provide-data)
* [Supported data types](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#data-type)
* [Model property names can matter](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#model-property-names)
* [How to refresh the component data](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#refresh-data)

## Data Binding vs Value Binding

This documentation site uses the terms *data binding* and *value binding* with the following meaning:

* Data binding is the process of providing a databound component with a collection of data (models) that it will display. Databound components include the Grid, DropDownList, Menu, and others.
* Value binding is the process of setting a component parameter, for example `<ComponentName ParameterName="@VariableName" />`. This includes both one-way binding and two-way binding with the `@bind-ParameterName="@VariableName"` syntax.

In other words, the Telerik UI for Blazor documentation uses the term *data binding* differently from the Microsoft documentation. The latter uses *data binding* to signify setting of parameters, for example `@bind="..."` or `@bind-Value="..."`.

## How to Provide Data

The Telerik Blazor components are detached from the application's data layer. They do not make data requests directly and rely on the application for data.

There are two main ways to provide data to the components:

* `Data` parameter - use it to provide all the data at once.
* [`OnRead` event](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/onread) - use it to load data on demand in chunks.

Hierarchy components like the TreeList and the TreeView don't have an `OnRead` event. Instead, they load data on demand via `OnExpand` events.

> warning Do not use `Data` and `OnRead` at the same time with the same component.
>
> The component model must be a `class` and not `struct`.
>
> The class properties should have getters and setters, otherwise data binding or editing may stop working.

## Data Type

All databound Telerik Blazor components expect their data to be `IEnumerable<T>`, where `T` can be any object type.

### Component Type

All databound components are generic and their type depends on the model type `T`. This is important when you need to define a component reference with the `@ref` directive:

> caption Defining reference to a databound component

```RAZOR.skip-repl
<TelerikGrid @ref="@Grid1" />
<TelerikComboBox @ref="@Combo1" />

@code {
    // incorrect
    private TelerikGrid Grid1 { get; set; }
    private TelerikComboBox Combo1 { get; set; }

    // correct
    private TelerikGrid<SampleModel> Grid1 { get; set; }
    private TelerikComboBox<SampleModel, int?> Combo1 { get; set; }
}
```

If the component `Data` is not set initially, set the `TItem` parameter to point to the model type. If the component has a `Value` parameter, then set `TValue` in this case as well.

> caption Setting TItem and TValue

```RAZOR.skip-repl
<TelerikGrid TItem="@SampleModel" />

<TelerikComboBox TItem="@SampleModel"
                 TValue="@(int?)"
                 @bind-Value="@ComboValue" />

@code {
    private int? ComboValue { get; set; }

    public class SampleModel
    {
        public int? Id { get; set; }
        public string Text { get; set; }
    }
}
```

## Model Property Names

Some components handle properties with specific names in a predefined way. For example, the Menu will automatically render the `Text` property of its items. If the property names are different, the component will expect additional configuration. All these specifics are described in each component documentation.

## Refresh Data

There are three ways to refresh the component data:

* [Bind the component to Observable data](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/observable-data). **This option applies only** if the `Data` parameter is set. The component will refresh automatically when items are **added or removed**.
* Call the component's `Rebind()` method. UI for Blazor version **3.3.0** exposed `Rebind()` for all databound components. Until then, the method was available only for the [components that have an `OnRead` event](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/onread#components-with-onread-event). If the component is databound via `OnRead`, the [`Rebind()` method will fire the `OnRead` event](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/onread#refresh-data).
* Reset the `Data` parameter reference. Sometimes, you may also need to call `StateHasChanged()` - for example, if the refreshing occurs in `OnAfterRenderAsync`.

The [example below](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/overview#example) demonstrates the second and third option. Also check [how to rebind and refresh a component with a `Timer`](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-rebind-timer).

### Reset the Collection Reference

The Blazor framework will fire `OnParametersSet` of a component only when it detects a change in the component's parameter values (such as `Data`). The change detection works like this:

* For strings and [value types](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/value-types) (numbers, dates, booleans), the detection occurs when the value changes.
* For [reference types](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/reference-types) (such as `IEnumerable` and any application-specific objects), the detection occurs when the object reference changes.

Thus, you will usually need to create a new reference for `Data` value in order to refresh the component.

### Example

> caption Call `Rebind()` or create new Data reference

```RAZOR
<TelerikGrid @ref="@GridRef"
             Data="@GridData"
             AutoGenerateColumns="true">
    <GridToolBarTemplate>
        <TelerikButton ThemeColor="@ThemeConstants.Button.ThemeColor.Primary"
                       OnClick="@RefreshGridData">Modify Grid Data And Refresh</TelerikButton>
    </GridToolBarTemplate>
</TelerikGrid>

@code {
    private TelerikGrid<SampleModel>? GridRef { get; set; }

    private List<SampleModel> GridData { get; set; } = new();

    private int LastId { get; set; }

    private void RefreshGridData()
    {
        GridData.RemoveAt(0);

        GridData.ElementAt(Random.Shared.Next(0, GridData.Count)).Text = DateTime.Now.Ticks.ToString();

        GridData.Add(new SampleModel()
        {
            Id = ++LastId,
            Text = "Text " + LastId
        });

        // Call Rebind...
        GridRef?.Rebind();

        // ...OR...

        // ...reset the object reference:
        //GridData = new List<SampleModel>(GridData);

        // call only if necessary
        //StateHasChanged();
    }

    protected override void OnInitialized()
    {
        for (int i = 1; i <= 5; i++)
        {
            GridData.Add(new SampleModel()
            {
                Id = ++LastId,
                Text = $"Text {LastId}"
            });
        }

        base.OnInitialized();
    }

    public class SampleModel
    {
        public int Id { get; set; }
        public string Text { get; set; } = string.Empty;
    }
}
```

## Next Steps

* [Data Binding with the OnRead event](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/onread)
* [Data Binding to Observable Data](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/observable-data)
* [Data Binding to cloud data services](https://www.telerik.com/blazor-ui/documentation/common-features/data-binding/cloud-services)