# Blazor TreeList CRUD Operations

The Telerik TreeList for Blazor supports create, update, and delete operations (CRUD) with different modes and user experience. The component also supports built-in `DataAnnotations` or custom validation. This page describes:

* [How the create, update, and delete operations work in the TreeList](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#basics).
* [What are the available edit modes and how to enable them](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#edit-modes).
* [The applicable TreeList commands](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#commands).
* [The applicable TreeList events](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#events).
* [How to change the built-in editors for certain data types](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#column-editors).
* [How to refresh the TreeList data after add, edit, and delete operations](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#rebinding-after-data-changes).
* [How the TreeList CRUD operations integrate with other component features](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#integration-with-other-features).

## Basics

The TreeList CRUD operations rely on the following algorithm:

1. Users execute [TreeList commands (**Edit**, **Save**, **Delete**, and more)](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#commands) with the mouse or keyboard.
2. The TreeList fires [events (`OnCreate`, `OnDelete`, `OnUpdate` and more)](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#events), which provide information what the user did or how the component data changed.
3. The application applies the changes to the TreeList data source in the above event handlers.
4. The TreeList rebinds to display the latest data.

### Model Requirements

Adding or editing rows in the TreeList sets the following requirements on the TreeList model:

* The TreeList model class must have a parameterless constructor. Otherwise, use the [TreeList `OnModelInit` event](https://www.telerik.com/blazor-ui/documentation/components/treelist/events#onmodelinit) to provide a data item instance [when the TreeList needs to create one](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances). Optinally, you can also [set some default values](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-default-value-for-new-row).
* There must be a non-editable property that serves as a unique identifier.
* All editable properties must be `public` and have setters. These properties must not be `readonly`.
* Self-referencing or inherited properties must not cause `StackOverflowException` or `AmbiguousMatchException` during [programmatic model instance creation](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances).

## Edit Modes

The TreeList offers several ways to add and edit rows with a different user experience:

* [*In-Cell*](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell)—users modify the TreeList content cell by cell.
* [*Inline*](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/inline)—users modify the TreeList content row by row.
* [*Popup*](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/popup)—users modify the TreeList content row by row in a modal popup form.

To allow users to add or edit values in the TreeList:

1. Set the `EditMode` parameter to a [member of the `TreeListEditMode` enum](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.treelisteditmode). The default `EditMode` parameter value is `None` and the built-in [`Add` and `Edit` commands](https://www.telerik.com/blazor-ui/documentation/components/treelist/columns/command#built-in-commands) don't work.
2. Define the required [command buttons](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#commands) and [events](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#events) for the selected edit mode and operations.

> caption Set up TreeList popup edit mode

```RAZOR.skip-repl
<TelerikTreeList EditMode="@TreeListEditMode.Popup"
                 OnUpdate="@OnTreeListUpdate">
    <TreeListColumns>
        <TreeListCommandColumn>
            <TreeListCommandButton Command="Edit">Edit</TreeListCommandButton>
        </TreeListCommandColumn>
    </TreeListColumns>
</TelerikTreeList>
```

> tip See the TreeList add and edit operations in action in the complete examples for TreeList [inline](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/inline#example), [in-cell](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell#example), and [popup](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/popup#example) editing.

> Editing multiple rows at the same time is not supported. You can [render editors in all TreeList data cells through column `<Template>`s](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-edit-all-rows-cells) as an alternative.

### Delete Operations

Delete operations provide the same user experience in all TreeList edit modes and require the same configuration:

* [**Delete** command button](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#commands).
* [`OnDelete` event](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#events).
* Optional `ConfirmDelete` TreeList parameter. It determines if the component will show a Dialog before firing `OnDelete`, so that users can abort the operation.

Delete operations can work even if the TreeList `EditMode` parameter value is `None`.

If the TreeList contains Delete command buttons that display and operate in edit mode, these buttons will fire the [`OnDelete` event](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#events) with a [cloned data item instance](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances) in the [event argument](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#treelistcommandeventargs). To find the original data item in the TreeList data source, use the item ID or [override the `Equals()` method of the TreeList model class](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-save-load-state-localstorage).

> tip See the delete operations in action in the complete examples for TreeList [inline](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/inline#example), [in-cell](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell#example) and [popup](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/popup#example) editing. Also check how to [customize the Delete Confirmation Dialog](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-customize-delete-confirmation-dialog).

## Commands

The TreeList provides the following built-in commands, which enable users to add, delete, and edit rows:

* `Add`—adds a new row and puts it in edit mode. Fires the `OnAdd` [event](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#events). If the command button is in the TreeList toolbar, the new row is created at root level. If the command button is in the command column, the new row is created as a child of the current row.
* `Cancel`—cancels the [row or cell](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#edit-modes) changes and exits edit mode. Fires the `OnCancel` event.
* `Delete`—deletes a row. Fires the `OnDelete` event.
* `Edit`—puts a TreeList row or cell in edit mode. Fires the `OnEdit` event.
* `Save`—confirms the row or cell changes and exits edit mode, if the user input is valid. Fires the `OnUpdate` event.

Users execute commands in the following ways:

* By clicking on [command buttons](https://www.telerik.com/blazor-ui/documentation/components/treelist/columns/command#the-treelistcommandbutton-tag).
* By clicking on editable cells in [in-cell edit mode](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell) and then anywhere else on the page.
* By using the [TreeList keyboard navigation](https://demos.telerik.com/blazor-ui/treelist/keyboard-navigation).

Command buttons can only reside in a [TreeList Command Column](https://www.telerik.com/blazor-ui/documentation/components/treelist/columns/command) or the [TreeList ToolBar](https://www.telerik.com/blazor-ui/documentation/components/treelist/toolbar). Each command button in the command column is visible only in display mode or only in edit mode, depending on the button's `ShowInEdit` boolean parameter value

You can also [trigger add and edit operations programmatically](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-add-edit-state) from anywhere on the web page through the [TreeList State](https://www.telerik.com/blazor-ui/documentation/components/treelist/state).

## Events

The following table describes the TreeList events, which are related to adding, deleting, and editing items. Also check the sections about [item instances](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances) and [event arguments](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#treelistcommandeventargs) below.

<style>
    .article table {
        table-layout: auto;
        word-break: normal;
    }
</style>

| Event         | Required                                                                                                                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                         | [Item Instance](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#treelistcommandeventargs) | If Cancelled                                               |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------- |
| `OnAdd`       | No                                                                                                                           | Fires on `Add` [command button](https://www.telerik.com/blazor-ui/documentation/components/treelist/columns/command) click, before the TreeList enters add mode. This event preceeds `OnCreate` or `OnCancel`.                                                                                                                                                                                                                                      | [New](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances)                     | TreeList remains in read mode.                             |
| `OnCancel`    | No                                                                                                                           | Fires on `Cancel` command invocation.                                                                                                                                                                                                                                                                                                                                                                                                               | [New or cloned](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances)           | TreeList remains in add or edit mode.                      |
| `OnCreate`    | To add new items.                                                                                                            | Fires on `Save` command invocation for new items. This event succeeds `OnAdd`.                                                                                                                                                                                                                                                                                                                                                                      | [New](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances)                     | TreeList remains in add mode.                              |
| `OnDelete`    | To [delete items](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#delete-operations).   | Fires on `Delete` command button click.                                                                                                                                                                                                                                                                                                                                                                                                             | [Original or cloned](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances)      | TreeList won't rebind. Deletion depends on the app itself. |
| `OnEdit`      | No                                                                                                                           | Fires on `Edit` command invocation, before the TreeList actually enters edit mode. This event preceeds `OnCreate` or `OnCancel`.                                                                                                                                                                                                                                                                                                                    | Original                                                                                                                       | TreeList remains in read mode.                             |
| `OnModelInit` | [Depends on the TreeList model type](https://www.telerik.com/blazor-ui/documentation/components/treelist/events#onmodelinit) | Fires when the TreeList requires a [new model instance](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances), which is immediately before `OnAdd` or immediately after `OnEdit`. <br /> Use this event when the TreeList model type is an [interface, abstract class, or has no parameterless constructor](https://www.telerik.com/blazor-ui/documentation/components/treelist/events#onmodelinit). | No event arguments                                                                                                             | Not cancellable                                            |
| `OnUpdate`    | To edit existing items.                                                                                                      | Fires on `Save` command invocation for existing items. This event succeeds `OnEdit`.                                                                                                                                                                                                                                                                                                                                                                | [Cloned](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances)                  | TreeList remains in edit mode.                             |

The following considerations apply for the TreeList CRUD events:

* Most events provide a [`TreeListCommandEventArgs` argument](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#treelistcommandeventargs) in the handler. `OnModelInit` has no event argument.
* All events, except `OnModelInit`, are cancellable and the user action can be prevented. Cancelling `OnDelete` does not automatically prevent item deletion from the TreeList data source. This depends entirely on the executed application code.
* The `OnCreate`, `OnDelete`, and `OnUpdate` events are required when using add, delete, and edit operations, respectively. The app must use these events to modify the TreeList data source. [The TreeList does not modify its data directly](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#item-instances).

Some events always fire in the same sequence, based on the user actions. In the list below, the value input and [validation](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/validation) occur between the second and third event:

* `OnModelInit`, `OnAdd`, and `OnCreate` for add operations
* `OnEdit`, `OnModelInit`, and `OnUpdate` for edit operations

Both user workflows can end with the `OnCancel` event instead of `OnCreate` or `OnUpdate`.

> Use `async Task` instead of `async void` for event handlers that execute awaitable operations. Otherwise the TreeList may show incorrect data, or the app may throw exceptions related to disposed objects or concurrency.

### Item Instances

The TreeList does not expose or modify its data items directly in add or edit mode. Instead, the component creates a new item instance or clones an existing one. The user is always changing the values of the separate item instance. The TreeList uses [`Activator.CreateInstance<TItem>()`](https://learn.microsoft.com/en-us/dotnet/api/system.activator.createinstance) and [`PropertyInfo.SetValue()`](https://learn.microsoft.com/en-us/dotnet/api/system.reflection.propertyinfo.setvalue) to create and populate items for add and edit mode. This approach:

* Allows users to cancel their changes and revert to the original data item values.
* Provides the app with full control over the data source.
* Sets some requirements [for the TreeList model class](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#model-requirements) and for [updating Entity Framework models](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-entity-framework-model-update).

### TreeListCommandEventArgs

All events in the [Events table](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#events), except `OnModelInit`, provide a [`TreeListCommandEventArgs`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.components.treelistcommandeventargs) event argument. It exposes the following properties:

| Property Name | Type                  | Description                                                                                                                                                                                                                                                 |
| ------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Field`       | `string`              | The [column `Field` name](https://www.telerik.com/blazor-ui/documentation/components/treelist/columns/bound#data-binding). Applicable only for [in-cell edit mode](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell).     |
| `IsCancelled` | `bool`                | Defines if the user action should be prevented. See the [Events table](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/overview#events) for details.                                                                            |
| `IsNew`       | `bool`                | Defines if `Item` is a newly added row or an existing row.                                                                                                                                                                                                  |
| `Items`       | `IEnumerable<object>` | The data item, which the user is adding, deleting, or editing. Cast the collection to the TreeList model type. Until [batch editing](https://feedback.telerik.com/blazor/1428492-batch-editing) is implemented, the collection can contain only one member. |
| `ParentItem`  | `object?`             | The parent of the data item, which the user is adding. Available only in the `OnCreate` event. Cast the object to the TreeList model type.                                                                                                                  |
| `Value`       | `object`              | The data item value, which the user is editing. You can cast it to the correct type, based on the `Field`. Applicable only for [in-cell edit mode](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell).                     |

## Column Editors

You can customize the column editors through the [column `EditorType` parameter](https://www.telerik.com/blazor-ui/documentation/components/treelist/columns/bound#data-operations), or by using an [editor template](https://www.telerik.com/blazor-ui/documentation/components/treelist/templates/editor). The `EditorType` parameter accepts a member of the `TreeListEditorType` enum:

| Column Field Type | Valid `TreeListEditorType` Enum Members                          |
| ----------------- | ---------------------------------------------------------------- |
| `bool`            | `CheckBox` (default) <br /> `Switch`                             |
| `DateTime`        | `DatePicker` (default) <br /> `DateTimePicker` <br> `TimePicker` |
| `string`          | `TextArea` <br /> `TextBox` (default)                            |

> caption Setting column editor type

```RAZOR.skip-repl
<TreeListColumn Field="@nameof(Race.StartDateTime)"
                EditorType="@TreeListEditorType.DateTimePicker" />
```

## Rebinding After Data Changes

During add, edit, and delete operations, the TreeList expects the application to make changes to the data source (database) and then provide the latest data to the component.

In the `OnCreate`, `OnDelete`, and `OnUpdate` event handler, the application must do one of the following:

* Make a read request to the database. Retrieve the latest data and set it as the new value of the TreeList `Data` parameter. The TreeList will rebind automatically. The following examples demonstrate this approach:
  * [Inline TreeList Editing](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/inline#example)
  * [Popup TreeList Editing](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/popup#example)
  * [In-Cell TreeList Editing](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell#example)
* [Use the event arguments to update the local item collection in the `Data` parameter manually](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-load-cached-data-after-crud-operations#data-parameter).

## Integration with Other Features

Updated rows comply with the current filter, search, and sort settings, just like all other rows. As a result, an updated row may render at a different place or disappear.

When editing a row with child items, it will collapse unless you override the `Equals()` method of the TreeList model class.

Learn more integration details for the [inline](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/inline#integration-with-other-features) and [in-cell](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell#integration-with-other-features) edit modes.

## New Row Position

You can control whether a newly added item appears at the top or bottom of the TreeList. Use the [`NewRowPosition`](https://www.telerik.com/blazor-ui/documentation/api/telerik.blazor.treelistnewrowposition) parameter to specify the position. This parameter does not affect Popup edit mode, which always displays a dialog for new items.

This configuration is available in InCell and Inline edit modes. For more details, see the [InCell Editing](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell#new-row-position) and [Inline Editing](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/inline#new-row-position) articles.

> When you set `NewRowPosition` to `Bottom`, add the new item at the end of your data collection in the `OnCreate` event handler. When set to `Top`, insert the new item at the beginning of the collection. This ensures the new row appears in the correct position in the view after successfully creating the new record.

> caption Example of adding a new item to the TreeList based on the `NewRowPosition` value

```C#.skip-repl
private void OnCreate(TreeListCommandEventArgs args)
{
    if (NewRowPosition == TreeListNewRowPosition.Bottom)
    {
        dataCollection.Add(newItem);
    }
    else // Top
    {
        dataCollection.Insert(0, newItem);
    }
}    
```

## Examples

See TreeList CRUD operations in action at:

* [TreeList Inline Editing](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/inline#example)
* [TreeList Popup Editing](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/popup#example)
* [TreeList In-Cell Editing](https://www.telerik.com/blazor-ui/documentation/components/treelist/editing/incell#example)
* [Online TreeList Demos](https://demos.telerik.com/blazor-ui/treelist/editing-inline)

## See Also

* [Enter and Exit TreeList Edit Mode Programmatically](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-add-edit-state)
* [Set Default Values for TreeList Add and Edit Mode](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-default-value-for-new-row)
* [Edit All TreeList Rows and Cells at the Same Time](https://www.telerik.com/blazor-ui/documentation/knowledge-base/grid-edit-all-rows-cells)
