ASP.NET Core Blazor input components
Note
This isn't the latest version of this article. For the current release, see the .NET 8 version of this article.
Warning
This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.
Important
This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
For the current release, see the .NET 8 version of this article.
This article describes Blazor's built-in input components.
Input components
The Blazor framework provides built-in input components to receive and validate user input. The built-in input components in the following table are supported in an EditForm with an EditContext.
The components in the table are also supported outside of a form in Razor component markup. Inputs are validated when they're changed and when a form is submitted.
Input component | Rendered as… |
---|---|
InputCheckbox | <input type="checkbox"> |
InputDate<TValue> | <input type="date"> |
InputFile | <input type="file"> |
InputNumber<TValue> | <input type="number"> |
InputRadio<TValue> | <input type="radio"> |
InputRadioGroup<TValue> | Group of child InputRadio<TValue> |
InputSelect<TValue> | <select> |
InputText | <input> |
InputTextArea | <textarea> |
For more information on the InputFile component, see ASP.NET Core Blazor file uploads.
Input component | Rendered as… |
---|---|
InputCheckbox | <input type="checkbox"> |
InputDate<TValue> | <input type="date"> |
InputNumber<TValue> | <input type="number"> |
InputSelect<TValue> | <select> |
InputText | <input> |
InputTextArea | <textarea> |
Note
InputRadio<TValue> and InputRadioGroup<TValue> components are available in ASP.NET Core 5.0 or later. For more information, select a 5.0 or later version of this article.
All of the input components, including EditForm, support arbitrary attributes. Any attribute that doesn't match a component parameter is added to the rendered HTML element.
Input components provide default behavior for validating when a field is changed:
- For input components in a form with an EditContext, the default validation behavior includes updating the field CSS class to reflect the field's state as valid or invalid with validation styling of the underlying HTML element.
- For controls that don't have an EditContext, the default validation reflects the valid or invalid state but does not provide validation styling to the underlying HTML element.
Some components include useful parsing logic. For example, InputDate<TValue> and InputNumber<TValue> handle unparseable values gracefully by registering unparseable values as validation errors. Types that can accept null values also support nullability of the target field (for example, int?
for a nullable integer).
For more information on the InputFile component, see ASP.NET Core Blazor file uploads.
Example form
The following Starship
type, which is used in several of this article's examples and examples in other Forms node articles, defines a diverse set of properties with data annotations:
Id
is required because it's annotated with the RequiredAttribute.Id
requires a value of at least one character but no more than 16 characters using the StringLengthAttribute.Description
is optional because it isn't annotated with the RequiredAttribute.Classification
is required.- The
MaximumAccommodation
property defaults to zero but requires a value from one to 100,000 per its RangeAttribute. IsValidatedDesign
requires that the property have atrue
value, which matches a selected state when the property is bound to a checkbox in the UI (<input type="checkbox">
).ProductionDate
is a DateTime and required.
Starship.cs
:
using System.ComponentModel.DataAnnotations;
namespace BlazorSample;
public class Starship
{
[Required]
[StringLength(16, ErrorMessage = "Identifier too long (16 character limit).")]
public string? Id { get; set; }
public string? Description { get; set; }
[Required]
public string? Classification { get; set; }
[Range(1, 100000, ErrorMessage = "Accommodation invalid (1-100000).")]
public int MaximumAccommodation { get; set; }
[Required]
[Range(typeof(bool), "true", "true", ErrorMessage = "Approval required.")]
public bool IsValidatedDesign { get; set; }
[Required]
public DateTime ProductionDate { get; set; }
}
using System.ComponentModel.DataAnnotations;
public class Starship
{
[Required]
[StringLength(16, ErrorMessage = "Identifier too long (16 character limit).")]
public string? Id { get; set; }
public string? Description { get; set; }
[Required]
public string? Classification { get; set; }
[Range(1, 100000, ErrorMessage = "Accommodation invalid (1-100000).")]
public int MaximumAccommodation { get; set; }
[Required]
[Range(typeof(bool), "true", "true",
ErrorMessage = "This form disallows unapproved ships.")]
public bool IsValidatedDesign { get; set; }
[Required]
public DateTime ProductionDate { get; set; }
}
using System.ComponentModel.DataAnnotations;
public class Starship
{
[Required]
[StringLength(16, ErrorMessage = "Identifier too long (16 character limit).")]
public string? Id { get; set; }
public string? Description { get; set; }
[Required]
public string? Classification { get; set; }
[Range(1, 100000, ErrorMessage = "Accommodation invalid (1-100000).")]
public int MaximumAccommodation { get; set; }
[Required]
[Range(typeof(bool), "true", "true",
ErrorMessage = "This form disallows unapproved ships.")]
public bool IsValidatedDesign { get; set; }
[Required]
public DateTime ProductionDate { get; set; }
}
using System;
using System.ComponentModel.DataAnnotations;
public class Starship
{
[Required]
[StringLength(16, ErrorMessage = "Identifier too long (16 character limit).")]
public string Id { get; set; }
public string Description { get; set; }
[Required]
public string Classification { get; set; }
[Range(1, 100000, ErrorMessage = "Accommodation invalid (1-100000).")]
public int MaximumAccommodation { get; set; }
[Required]
[Range(typeof(bool), "true", "true",
ErrorMessage = "This form disallows unapproved ships.")]
public bool IsValidatedDesign { get; set; }
[Required]
public DateTime ProductionDate { get; set; }
}
using System;
using System.ComponentModel.DataAnnotations;
public class Starship
{
[Required]
[StringLength(16, ErrorMessage = "Identifier too long (16 character limit).")]
public string Id { get; set; }
public string Description { get; set; }
[Required]
public string Classification { get; set; }
[Range(1, 100000, ErrorMessage = "Accommodation invalid (1-100000).")]
public int MaximumAccommodation { get; set; }
[Required]
[Range(typeof(bool), "true", "true",
ErrorMessage = "This form disallows unapproved ships.")]
public bool IsValidatedDesign { get; set; }
[Required]
public DateTime ProductionDate { get; set; }
}
The following form accepts and validates user input using:
- The properties and validation defined in the preceding
Starship
model. - Several of Blazor's built-in input components.
When the model property for the ship's classification (Classification
) is set, the option matching the model is checked. For example, checked="@(Model!.Classification == "Exploration")"
for the classification of an exploration ship. The reason for explicitly setting the checked option is that the value of a <select>
element is only present in the browser. If the form is rendered on the server after it's submitted, any state from the client is overridden with state from the server, which doesn't ordinarily mark an option as checked. By setting the checked option from the model property, the classification always reflects the model's state. This preserves the classification selection across form submissions that result in the form rerendering on the server. In situations where the form isn't rerendered on the server, such as when the Interactive Server render mode is applied directly to the component, explicit assignment of the checked option from the model isn't necessary because Blazor preserves the state for the <select>
element on the client.
Starship3.razor
:
@page "/starship-3"
@inject ILogger<Starship3> Logger
<h1>Starfleet Starship Database</h1>
<h2>New Ship Entry Form</h2>
<EditForm Model="Model" OnValidSubmit="Submit" FormName="Starship3">
<DataAnnotationsValidator />
<ValidationSummary />
<div>
<label>
Identifier:
<InputText @bind-Value="Model!.Id" />
</label>
</div>
<div>
<label>
Description (optional):
<InputTextArea @bind-Value="Model!.Description" />
</label>
</div>
<div>
<label>
Primary Classification:
<InputSelect @bind-Value="Model!.Classification">
<option value="">
Select classification ...
</option>
<option checked="@(Model!.Classification == "Exploration")"
value="Exploration">
Exploration
</option>
<option checked="@(Model!.Classification == "Diplomacy")"
value="Diplomacy">
Diplomacy
</option>
<option checked="@(Model!.Classification == "Defense")"
value="Defense">
Defense
</option>
</InputSelect>
</label>
</div>
<div>
<label>
Maximum Accommodation:
<InputNumber @bind-Value="Model!.MaximumAccommodation" />
</label>
</div>
<div>
<label>
Engineering Approval:
<InputCheckbox @bind-Value="Model!.IsValidatedDesign" />
</label>
</div>
<div>
<label>
Production Date:
<InputDate @bind-Value="Model!.ProductionDate" />
</label>
</div>
<div>
<button type="submit">Submit</button>
</div>
</EditForm>
@code {
[SupplyParameterFromForm]
private Starship? Model { get; set; }
protected override void OnInitialized() =>
Model ??= new() { ProductionDate = DateTime.UtcNow };
private void Submit()
{
Logger.LogInformation("Id = {Id} Description = {Description} " +
"Classification = {Classification} MaximumAccommodation = " +
"{MaximumAccommodation} IsValidatedDesign = " +
"{IsValidatedDesign} ProductionDate = {ProductionDate}",
Model?.Id, Model?.Description, Model?.Classification,
Model?.MaximumAccommodation, Model?.IsValidatedDesign,
Model?.ProductionDate);
}
}
@page "/starship-3"
@inject ILogger<Starship3> Logger
<h1>Starfleet Starship Database</h1>
<h2>New Ship Entry Form</h2>
<EditForm Model="Model" OnValidSubmit="Submit">
<DataAnnotationsValidator />
<ValidationSummary />
<div>
<label>
Identifier:
<InputText @bind-Value="Model!.Id" />
</label>
</div>
<div>
<label>
Description (optional):
<InputTextArea @bind-Value="Model!.Description" />
</label>
</div>
<div>
<label>
Primary Classification:
<InputSelect @bind-Value="Model!.Classification">
<option value="">Select classification ...</option>
<option value="Exploration">Exploration</option>
<option value="Diplomacy">Diplomacy</option>
<option value="Defense">Defense</option>
</InputSelect>
</label>
</div>
<div>
<label>
Maximum Accommodation:
<InputNumber @bind-Value="Model!.MaximumAccommodation" />
</label>
</div>
<div>
<label>
Engineering Approval:
<InputCheckbox @bind-Value="Model!.IsValidatedDesign" />
</label>
</div>
<div>
<label>
Production Date:
<InputDate @bind-Value="Model!.ProductionDate" />
</label>
</div>
<div>
<button type="submit">Submit</button>
</div>
</EditForm>
@code {
private Starship? Model { get; set; }
protected override void OnInitialized() =>
Model ??= new() { ProductionDate = DateTime.UtcNow };
private void Submit()
{
Logger.LogInformation("Id = {Id} Description = {Description} " +
"Classification = {Classification} MaximumAccommodation = " +
"{MaximumAccommodation} IsValidatedDesign = " +
"{IsValidatedDesign} ProductionDate = {ProductionDate}",
Model?.Id, Model?.Description, Model?.Classification,
Model?.MaximumAccommodation, Model?.IsValidatedDesign,
Model?.ProductionDate);
}
}
The EditForm in the preceding example creates an EditContext based on the assigned Starship
instance (Model="..."
) and handles a valid form. The next example demonstrates how to assign an EditContext to a form and validate when the form is submitted.
In the following example:
- A shortened version of the earlier
Starfleet Starship Database
form (Starship3
component) is used that only accepts a value for the starship's Id. The otherStarship
properties receive valid default values when an instance of theStarship
type is created. - The
Submit
method executes when theSubmit
button is selected. - The form is validated by calling EditContext.Validate in the
Submit
method. - Logging is executed depending on the validation result.
Note
Submit
in the next example is demonstrated as an asynchronous method because storing form values often uses asynchronous calls (await ...
). If the form is used in a test app as shown, Submit
merely runs synchronously. For testing purposes, ignore the following build warning:
This async method lacks 'await' operators and will run synchronously. ...
Starship4.razor
:
@page "/starship-4"
@inject ILogger<Starship4> Logger
<EditForm EditContext="editContext" OnSubmit="Submit" FormName="Starship4">
<DataAnnotationsValidator />
<div>
<label>
Identifier:
<InputText @bind-Value="Model!.Id" />
</label>
</div>
<div>
<button type="submit">Submit</button>
</div>
</EditForm>
@code {
private EditContext? editContext;
[SupplyParameterFromForm]
private Starship? Model { get; set; }
protected override void OnInitialized()
{
Model ??=
new()
{
Id = "NCC-1701",
Classification = "Exploration",
MaximumAccommodation = 150,
IsValidatedDesign = true,
ProductionDate = new DateTime(2245, 4, 11)
};
editContext = new(Model);
}
private async Task Submit()
{
if (editContext != null && editContext.Validate())
{
Logger.LogInformation("Submit called: Form is valid");
// await ...
}
else
{
Logger.LogInformation("Submit called: Form is INVALID");
}
}
}
@page "/starship-4"
@inject ILogger<Starship4> Logger
<EditForm EditContext="editContext" OnSubmit="Submit">
<DataAnnotationsValidator />
<div>
<label>
Identifier:
<InputText @bind-Value="Model!.Id" />
</label>
</div>
<div>
<button type="submit">Submit</button>
</div>
</EditForm>
@code {
private EditContext? editContext;
private Starship Model { get; set; }
protected override void OnInitialized()
{
Model ??=
new()
{
Id = "NCC-1701",
Classification = "Exploration",
MaximumAccommodation = 150,
IsValidatedDesign = true,
ProductionDate = new DateTime(2245, 4, 11)
};
editContext = new(Model);
}
private async Task Submit()
{
if (editContext != null && editContext.Validate())
{
Logger.LogInformation("Submit called: Form is valid");
// await ...
}
else
{
Logger.LogInformation("Submit called: Form is INVALID");
}
}
}
Note
Changing the EditContext after it's assigned is not supported.
Multiple option selection with the InputSelect
component
Binding supports multiple
option selection with the InputSelect<TValue> component. The @onchange
event provides an array of the selected options via event arguments (ChangeEventArgs
). The value must be bound to an array type, and binding to an array type makes the multiple
attribute optional on the InputSelect<TValue> tag.
In the following example, the user must select at least two starship classifications but no more than three classifications.
Starship5.razor
:
@page "/starship-5"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship5> Logger
<h1>Bind Multiple <code>InputSelect</code> Example</h1>
<EditForm EditContext="editContext" OnValidSubmit="Submit" FormName="Starship5">
<DataAnnotationsValidator />
<ValidationSummary />
<div>
<label>
Select classifications (Minimum: 2, Maximum: 3):
<InputSelect @bind-Value="Model!.SelectedClassification">
<option value="@Classification.Exploration">Exploration</option>
<option value="@Classification.Diplomacy">Diplomacy</option>
<option value="@Classification.Defense">Defense</option>
<option value="@Classification.Research">Research</option>
</InputSelect>
</label>
</div>
<div>
<button type="submit">Submit</button>
</div>
</EditForm>
@if (Model?.SelectedClassification?.Length > 0)
{
<div>@string.Join(", ", Model.SelectedClassification)</div>
}
@code {
private EditContext? editContext;
[SupplyParameterFromForm]
private Starship? Model { get; set; }
protected override void OnInitialized()
{
Model = new();
editContext = new(Model);
}
private void Submit()
{
Logger.LogInformation("Submit called: Processing the form");
}
private class Starship
{
[Required]
[MinLength(2, ErrorMessage = "Select at least two classifications.")]
[MaxLength(3, ErrorMessage = "Select no more than three classifications.")]
public Classification[]? SelectedClassification { get; set; } =
new[] { Classification.None };
}
private enum Classification { None, Exploration, Diplomacy, Defense, Research }
}
@page "/starship-5"
@using System.ComponentModel.DataAnnotations
@inject ILogger<Starship5> Logger
<h1>Bind Multiple <code>InputSelect</code> Example</h1>
<EditForm EditContext="editContext" OnValidSubmit="Submit">
<DataAnnotationsValidator />
<ValidationSummary />
<div>
<label>
Select classifications (Minimum: 2, Maximum: 3):
<InputSelect @bind-Value="Model!.SelectedClassification">
<option value="@Classification.Exploration">Exploration</option>
<option value="@Classification.Diplomacy">Diplomacy</option>
<option value="@Classification.Defense">Defense</option>
<option value="@Classification.Research">Research</option>
</InputSelect>
</label>
</div>
<div>
<button type="submit">Submit</button>
</div>
</EditForm>
@if (Model?.SelectedClassification?.Length > 0)
{
<div>@string.Join(", ", Model.SelectedClassification)</div>
}
@code {
private EditContext? editContext;
private Starship? Model { get; set; }
protected override void OnInitialized()
{
Model ??= new();
editContext = new(Model);
}
private void Submit()
{
Logger.LogInformation("Submit called: Processing the form");
}
private class Starship
{
[Required]
[MinLength(2, ErrorMessage = "Select at least two classifications.")]
[MaxLength(3, ErrorMessage = "Select no more than three classifications.")]
public Classification[]? SelectedClassification { get; set; } =
new[] { Classification.None };
}
private enum Classification { None, Exploration, Diplomacy, Defense, Research }
}
For information on how empty strings and null
values are handled in data binding, see the Binding InputSelect
options to C# object null
values section.
Binding InputSelect
options to C# object null
values
For information on how empty strings and null
values are handled in data binding, see ASP.NET Core Blazor data binding.
Display name support
Several built-in components support display names with the InputBase<TValue>.DisplayName parameter.
In the Starfleet Starship Database
form (Starship3
component) of the Example form section, the production date of a new starship doesn't specify a display name:
<label>
Production Date:
<InputDate @bind-Value="Model!.ProductionDate" />
</label>
If the field contains an invalid date when the form is submitted, the error message doesn't display a friendly name. The field name, "ProductionDate
" doesn't have a space between "Production
" and "Date
" when it appears in the validation summary:
The ProductionDate field must be a date.
Set the DisplayName property to a friendly name with a space between the words "Production
" and "Date
":
<label>
Production Date:
<InputDate @bind-Value="Model!.ProductionDate"
DisplayName="Production Date" />
</label>
The validation summary displays the friendly name when the field's value is invalid:
The Production Date field must be a date.
Error message template support
InputDate<TValue> and InputNumber<TValue> support error message templates:
In the Starfleet Starship Database
form (Starship3
component) of the Example form section with a friendly display name assigned, the Production Date
field produces an error message using the following default error message template:
The {0} field must be a date.
The position of the {0}
placeholder is where the value of the DisplayName property appears when the error is displayed to the user.
<label>
Production Date:
<InputDate @bind-Value="Model!.ProductionDate"
DisplayName="Production Date" />
</label>
The Production Date field must be a date.
Assign a custom template to ParsingErrorMessage to provide a custom message:
<label>
Production Date:
<InputDate @bind-Value="Model!.ProductionDate"
DisplayName="Production Date"
ParsingErrorMessage="The {0} field has an incorrect date value." />
</label>
The Production Date field has an incorrect date value.
In the Starfleet Starship Database
form (Starship3
component) of the Example form section uses a default error message template:
The {0} field must be a date.
The position of the {0}
placeholder is where the value of the DisplayName property appears when the error is displayed to the user.
<label>
Production Date:
<InputDate @bind-Value="Model!.ProductionDate" />
</label>
The ProductionDate field must be a date.
Assign a custom template to ParsingErrorMessage to provide a custom message:
<label>
Production Date:
<InputDate @bind-Value="Model!.ProductionDate"
ParsingErrorMessage="The {0} field has an incorrect date value." />
</label>
The ProductionDate field has an incorrect date value.