# Blazor Form Items Overview

You can customize the [default editors](https://www.telerik.com/blazor-ui/documentation/components/form/overview#automatic-generation-of-fields) by using instances of the `FormItem` tag. Those instances should be in the `FormItems` collection.

In this article:

* [FormItem parameters](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/overview#formitem-parameters)
* [Combine explicit and autogenerated Form fields](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/overview#add-form-fields-to-autogenerated-ones)
* [UI rendering and performance optimization inside the Form](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/overview#ui-rendering-inside-the-form)

## FormItem Parameters

Each custom editor is expressed through the `FormItem` tag. You can define a collection of those editors in the `FormItems` tag that is a child of the `TelerikForm` tag. You can find some [code examples](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/overview#example) below.

The `FormItem` tag exposes the following parameters which you can use to customize the editors:

* `LabelText` - `string` - defines the label for the associated editor. This parameter provides more compact syntax for the `<label for="myEditorId">` HTML tag.

* `Id` - `string` - maps to the `id` HTML attribute of the `<input>` tag.

* `Hint` - `string` - defines a hint for the user on the place of the validation message. If a validation error occurs the hint will be replaced by the corresponding validation message.

* `Enabled` - `bool` - whether the editor is enabled. Defaults to `true`. If it is not specifically defined in the `FormItem` markup, it will take its value from the `[Editable]` data annotation attribute of the item.

* `Field` - `string` - the name of the field in the model that the editor will render for 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)`). If you are using its [Template](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/template) to provide a custom editor, the `Field` parameter is not required.

* `FieldType` - `string` - the data type of the `Field`. This parameter should be provided if the type of the property in the model can not be extracted using reflection, for example it is an `object` and you would like to render a `NumericTextBox`.

* `ColSpan` - `int` - defines the `colspan` attribute. This parameter is applicable when the FormItems are divided in multiple columns in a single group. See the [FormGroups](https://www.telerik.com/blazor-ui/documentation/components/form/formgroups) article for an example.

* `Class` - `string` - adds a custom CSS class to the `k-form-field` div tag.

* `Template` - `RenderFragment` - allows you to change the [default editor](https://www.telerik.com/blazor-ui/documentation/components/form/overview#automatic-generation-of-fields) altogether. For more information see the [Template](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/template) article.

### Example

> caption How to use and configure FormItem instances

<demo metaUrl="client/form/overview/example-2/" height="600"></demo>

## Add Form Fields to Autogenerated Ones

To combine manually defined with autogenerated fields, use an instance of the `FormAutoGeneratedItems` tag inside the `FormItems` collection.

> caption Basic configuration of the Hybrid Form.

<demo metaUrl="client/form/overview/example-1/" height="570"></demo>

## UI Rendering inside the Form

When the user changes a value in a non-template Form item, the other Form items don't re-render. This default behavior serves as a performance optimization. In some scenarios, the app may need other form items to update too, for example:

* When the value in one Form item affects values in other Form items.
* When Form items show or hide, depending on the value in other Form items.

In such cases, there are a few ways to trigger re-rendering and UI refresh inside or outside the Form:

* Use a Telerik input component inside a [Form item `<Template>`](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/template). Define two-way binding for the `Value` parameter, or use `Value`, `ValueChanged`, and `ValueExpression`.
* Use a custom component with two-way parameter binding for the respective Form model property. Alternatively, use one-way binding, but implement an `EventCallback` that updates the model property value.
* Call the [`Refresh()` method of the Form](https://www.telerik.com/blazor-ui/documentation/components/form/overview#form-reference-and-methods). The method will re-render the Form itself.
* Subscribe to the [`OnUpdate` event of the Form](https://www.telerik.com/blazor-ui/documentation/components/form/events#onupdate). The event is an `EventCallback`, so it will update the whole Razor component, which holds the Form.
* Call `StateHasChanged()` inside the Razor component, which holds the Form. This will re-render the whole Razor component, including the Form.

The example below demonstrates all of the above options. Note the differences in the two custom components:

* `ChildTwo.razor` supports two-way binding with an `EventCallback` for its `Value` parameter.
* `ChildOne.razor` does not support two-way binding and uses an `Action` instead of an `EventCallback`.

> caption How to re-render all Form Items or the Form's parent component

```RAZOR.skip-repl Home.razor
@using System.ComponentModel.DataAnnotations

<p>Type in the Form textboxes and observe the different results.</p>

<p>
    <label class="k-checkbox-label">
        <TelerikCheckBox @bind-Value="@ShouldUseOnUpdate" />
        Use the <strong>Form &nbsp;<code>OnUpdate</code>&nbsp; event (an &nbsp;<code>EventCallback</code>)</strong> to
        re-render inside and outside the Form
    </label>
</p>

<TelerikForm @ref="@FormRef"
             Model="@Employee"
             OnUpdate="@OnFormUpdate">
    <FormValidation>
        <DataAnnotationsValidator />
    </FormValidation>
    <FormItems>
        <FormItem Field="@nameof(Person.Name)" LabelText="No Template - no re-render without OnUpdate." />
        <FormItem Field="@nameof(Person.Name)">
            <Template>
                <label class="k-label k-form-label" style="color: var(--kendo-color-success)">
                    Telerik component - re-render inside and outside the Form.
                </label>
                <div class="k-form-field-wrap">
                    <TelerikTextBox @bind-Value="@Employee.Name" DebounceDelay="0" />
                    <TelerikValidationMessage For="@( () => Employee.Name )" />
                </div>
            </Template>
        </FormItem>
        <FormItem Field="@nameof(Person.Name)">
            <Template>
                <label class="k-label k-form-label" style="color: var(--kendo-color-success)">
                    Custom component with two-way binding - re-render inside and outside the Form.
                </label>
                <div class="k-form-field-wrap">
                    <ChildTwo @bind-Value="@Employee.Name" />
                    <TelerikValidationMessage For="@( () => Employee.Name )" />
                </div>
            </Template>
        </FormItem>
        <FormItem Field="@nameof(Person.Name)">
            <Template>
                <label class="k-label k-form-label" style="color: var(--kendo-color-success)">
                    Custom component with one-way binding and EventCallback -
                    re-render inside and outside the Form.
                </label>
                <div class="k-form-field-wrap">
                    <ChildTwo Value="@Employee.Name"
                                 ValueChanged="@OnChildTwoChange_EventCallback"
                                 ValueExpression="@( () => Employee.Name )" />
                    <TelerikValidationMessage For="@( () => Employee.Name )" />
                </div>
            </Template>
        </FormItem>
        <FormItem Field="@nameof(Person.Name)">
            <Template>
                <label class="k-label k-form-label" style="color: var(--kendo-color-warning)">
                    Custom component with one-way binding and Form &nbsp;<code>Refresh()</code>&nbsp; -
                    re-render inside the Form.
                </label>
                <div class="k-form-field-wrap">
                    <ChildOne Value="@Employee.Name"
                                 ValueExpression="@( () => Employee.Name )"
                                 OnChange="@OnChildOneChange_Refresh" />
                    <TelerikValidationMessage For="@( () => Employee.Name )" />
                </div>
            </Template>
        </FormItem>
        <FormItem Field="@nameof(Person.Name)">
            <Template>
                <label class="k-label k-form-label" style="color: var(--kendo-color-tertiary)">
                    Custom component with one-way binding and &nbsp;<code>StateHasChanged()</code>&nbsp; -
                    re-render inside and outside the Form.
                </label>
                <div class="k-form-field-wrap">
                    <ChildOne Value="@Employee.Name"
                                 ValueExpression="@( () => Employee.Name )"
                                 OnChange="@OnChildOneChange_StateHasChanged" />
                    <TelerikValidationMessage For="@( () => Employee.Name )" />
                </div>
            </Template>
        </FormItem>
    </FormItems>
</TelerikForm>

<br />

<p>&nbsp;<code>Employee.Name</code>&nbsp; in UI outside the Form: <strong>@Employee.Name</strong></p>

<TelerikButton OnClick="@( () => { } )"
               ButtonType="@ButtonType.Button">
    Execute EventCallback - re-render inside and outside the Form
</TelerikButton>

@code {
    private TelerikForm? FormRef { get; set; }

    private Person Employee { get; set; } = new();

    private bool ShouldUseOnUpdate { get; set; }

    private EventCallback OnFormUpdate => ShouldUseOnUpdate ?
        EventCallback.Factory.Create(this, OnFormUpdateHandler) :
        default(EventCallback);

    private void OnFormUpdateHandler()
    {
        // OnUpdate is an EventCallback.
        // Blazor calls StateHasChanged() automatically to update the UI
        // of the whole Razor component, which holds the Form.
    }

    private void OnChildTwoChange_EventCallback(string newValue)
    {
        Employee.Name = newValue;
    }

    private void OnChildOneChange_Refresh(string newValue)
    {
        Employee.Name = newValue;

        if (!ShouldUseOnUpdate)
        {
            FormRef?.Refresh();
        }
    }

    private void OnChildOneChange_StateHasChanged(string newValue)
    {
        Employee.Name = newValue;

        if (!ShouldUseOnUpdate)
        {
            StateHasChanged();
        }
    }

    public class Person
    {
        [Required]
        public string Name { get; set; }

        public Person()
        {
            Name = "John Doe";
        }
    }
}
```

```RAZOR ChildTwo.razor
@using System.Linq.Expressions

<TelerikTextBox Value="@Value"
                ValueChanged="@TextBoxValueChanged"
                ValueExpression="@ValueExpression"
                DebounceDelay="0" />

@code {
    [Parameter]
    public string Value { get; set; } = string.Empty;

    // This parameter is an EventCallback.
    // It will refresh the whole parent component's UI.
    [Parameter]
    public EventCallback<string> ValueChanged { get; set; }

    // Get a validation expression from a parent component.
    // See https://www.telerik.com/blazor-ui/documentation/knowledge-base/inputs-validation-child-component
    [Parameter]
    public Expression<Func<string>>? ValueExpression { get; set; }

    private async Task TextBoxValueChanged(string newValue)
    {
        Value = newValue;

        if (ValueChanged.HasDelegate)
        {
            await ValueChanged.InvokeAsync(newValue);
        }
    }
}
```

```RAZOR ChildOne.razor
@using System.Linq.Expressions

<TelerikTextBox Value="@Value"
                ValueChanged="@TextBoxValueChanged"
                ValueExpression="@ValueExpression"
                DebounceDelay="0" />

@code {
    [Parameter]
    public string Value { get; set; } = string.Empty;

    // This parameter is an Action instead of EventCallback.
    // It doesn't refresh the whole parent component's UI,
    // for example, for performance optimization.
    [Parameter]
    public Action<string>? OnChange { get; set; }

    // Get a validation expression from a parent component.
    // See https://www.telerik.com/blazor-ui/documentation/knowledge-base/inputs-validation-child-component
    [Parameter]
    public Expression<Func<string>>? ValueExpression { get; set; }

    private void TextBoxValueChanged(string newValue)
    {
        Value = newValue;

        OnChange?.Invoke(newValue);
    }
}
```

## Next Steps

* [Configure Form button](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/buttons)
* [Define Form item templates](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/template)
* [Define a template for all Form groups and items](https://www.telerik.com/blazor-ui/documentation/components/form/formitems/template)

## See Also

* [Online demo: Form Items](https://demos.telerik.com/blazor-ui/form/overview)
* [Form Groups](https://www.telerik.com/blazor-ui/documentation/components/form/formgroups)
* [Form Orientation](https://www.telerik.com/blazor-ui/documentation/components/form/orientation)
* [Validate in Child Component](https://www.telerik.com/blazor-ui/documentation/knowledge-base/inputs-validation-child-component)
