Class SfTextBox
The TextBox is an input element that allows to get input from the user. It allows the user to edit or display the text value.
Inherited Members
Namespace: Syncfusion.Blazor.Inputs
Assembly: Syncfusion.Blazor.dll
Syntax
public class SfTextBox : SfInputTextBase<string>Remarks
The SfTextBox component supports both single-line and multiline input modes. It can be configured with floating labels, placeholder text, clear button functionality, and various input types. The component inherits from SfInputTextBase<TValue> providing base functionality for text input operations.
Examples
The following code example demonstrates how to create a basic TextBox with floating label and clear button:
<SfTextBox @bind-Value="@textValue"
Placeholder="Enter your name"
FloatLabelType="FloatLabelType.Auto"
ShowClearButton="true">
</SfTextBox>
@code {
private string textValue = "";
}Constructors
SfTextBox()
Declaration
public SfTextBox()Properties
Autocomplete
Gets or sets a value indicating whether the browser should automatically complete or suggest values for the TextBox component.
Declaration
public AutoComplete Autocomplete { get; set; }Property Value
| Type | Description |
|---|---|
| AutoComplete | One of the AutoComplete enumeration values. The default value is On. Possible values are: |
Remarks
This property controls the HTML autocomplete attribute behavior. When enabled, browsers may display a dropdown list of previously entered values for the same field.
Examples
<SfTextBox Autocomplete="AutoComplete.Off" Placeholder="Enter password"></SfTextBox>BaseAutocomplete
Declaration
protected override string BaseAutocomplete { get; set; }Property Value
| Type |
|---|
| System.String |
Overrides
BaseFloatLabelType
Declaration
protected override FloatLabelType BaseFloatLabelType { get; set; }Property Value
| Type |
|---|
| FloatLabelType |
Overrides
BaseHtmlAttributes
Declaration
protected override Dictionary<string, object> BaseHtmlAttributes { get; set; }Property Value
| Type |
|---|
| System.Collections.Generic.Dictionary<System.String, System.Object> |
Overrides
BaseInputAttributes
Declaration
protected override Dictionary<string, object> BaseInputAttributes { get; set; }Property Value
| Type |
|---|
| System.Collections.Generic.Dictionary<System.String, System.Object> |
Overrides
BaseIsReadOnlyInput
Declaration
protected override bool BaseIsReadOnlyInput { get; set; }Property Value
| Type |
|---|
| System.Boolean |
Overrides
BasePlaceholder
Declaration
protected override string BasePlaceholder { get; set; }Property Value
| Type |
|---|
| System.String |
Overrides
BaseReadonly
Declaration
protected override bool BaseReadonly { get; set; }Property Value
| Type |
|---|
| System.Boolean |
Overrides
BaseShowClearButton
Declaration
protected override bool BaseShowClearButton { get; set; }Property Value
| Type |
|---|
| System.Boolean |
Overrides
BaseTabIndex
Declaration
protected override int BaseTabIndex { get; set; }Property Value
| Type |
|---|
| System.Int32 |
Overrides
BaseWidth
Declaration
protected override string BaseWidth { get; set; }Property Value
| Type |
|---|
| System.String |
Overrides
Blur
Gets or sets the event callback that will be invoked when the TextBox loses focus.
Declaration
public EventCallback<FocusOutEventArgs> Blur { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<FocusOutEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the TextBox loses focus. The callback receives a FocusOutEventArgs containing event data. |
Remarks
The Blur event is triggered when the user clicks outside the TextBox or navigates away from it using keyboard navigation (such as pressing Tab). This event is useful for performing validation, saving changes, or updating the UI when the user finishes interacting with the TextBox.
Examples
<SfTextBox Placeholder="Enter your name" Blur="@OnBlur">
</SfTextBox>
@code{
private void OnBlur(FocusOutEventArgs args)
{
// Perform validation or other actions when TextBox loses focus
Console.WriteLine("TextBox lost focus");
}
}ContainerClass
Declaration
protected override string ContainerClass { get; set; }Property Value
| Type |
|---|
| System.String |
Overrides
Created
Gets or sets the event callback that will be invoked when the TextBox component is created.
Declaration
public EventCallback<object> Created { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.Object> | An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the TextBox component is successfully created and rendered. The callback receives an System.Object parameter. |
Remarks
The Created event is triggered after the TextBox component has been fully initialized and rendered in the DOM. This event is useful for performing initialization tasks, setting up additional configurations, or integrating with JavaScript libraries that require the component to be fully rendered.
Examples
<SfTextBox Placeholder="Enter text" Created="@OnCreated">
</SfTextBox>
@code{
private void OnCreated(object args)
{
// Component initialization logic
Console.WriteLine("TextBox component created successfully");
}
}Destroyed
Gets or sets the event callback that will be invoked when the TextBox component is destroyed.
Declaration
public EventCallback<object> Destroyed { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<System.Object> | An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the TextBox component is being destroyed or removed from the DOM. The callback receives an System.Object parameter. |
Remarks
The Destroyed event is triggered when the TextBox component is being disposed or removed from the component tree. This event provides an opportunity to perform cleanup operations, such as removing event listeners, clearing timers, or releasing resources that were allocated during the component's lifecycle.
Examples
<SfTextBox Placeholder="Enter text" Destroyed="@OnDestroyed">
</SfTextBox>
@code{
private void OnDestroyed(object args)
{
// Cleanup logic
Console.WriteLine("TextBox component destroyed");
}
}FloatLabelType
Gets or sets the floating label behavior of the SfTextBox component. The Placeholder text acts as a floating label.
Declaration
public FloatLabelType FloatLabelType { get; set; }Property Value
| Type | Description |
|---|---|
| FloatLabelType | One of the FloatLabelType enumeration values. The default value is Never. |
Remarks
The floating label behavior determines how the placeholder text is displayed:
Examples
The following example demonstrates setting the floating label as Auto:
<SfTextBox FloatLabelType="FloatLabelType.Auto" Placeholder="Enter a value"></SfTextBox>Focus
Gets or sets the event callback that will be invoked when the TextBox gets focus.
Declaration
public EventCallback<FocusInEventArgs> Focus { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<FocusInEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the TextBox receives focus. The callback receives a FocusInEventArgs containing event data. |
Remarks
The Focus event is triggered when the user clicks on the TextBox, navigates to it using keyboard navigation (such as Tab key), or when focus is programmatically set to the component. This event is useful for highlighting the TextBox, showing additional UI elements, or preparing the component for user input.
Examples
<SfTextBox Placeholder="Enter your email" Focus="@OnFocus">
</SfTextBox>
@code{
private void OnFocus(FocusInEventArgs args)
{
// Perform actions when TextBox gains focus
Console.WriteLine("TextBox gained focus");
}
}HtmlAttributes
Gets or sets a collection of additional HTML attributes that will be applied to the outer wrapper element of the SfTextBox component.
Declaration
public Dictionary<string, object> HtmlAttributes { get; set; }Property Value
| Type | Description |
|---|---|
| System.Collections.Generic.Dictionary<System.String, System.Object> | A System.Collections.Generic.Dictionary<, > where the key is the attribute name and the value is the attribute value. The default value is |
Remarks
This property allows you to add custom HTML attributes to the TextBox wrapper element, such as:
Note: If you configure both a component property and its equivalent HTML attribute, the component property takes precedence.
Examples
<SfTextBox HtmlAttributes="@customAttributes">
</SfTextBox>
@code {
Dictionary<string, object> customAttributes = new Dictionary<string, object>()
{
{ "title", "Enter your full name" },
{ "class", "custom-textbox" },
{ "data-testid", "name-input" }
};
}Input
Gets or sets the event callback that will be invoked when the user types or pastes text into the TextBox.
Declaration
public EventCallback<InputEventArgs> Input { get; set; }Property Value
| Type |
|---|
| Microsoft.AspNetCore.Components.EventCallback<InputEventArgs> |
Remarks
The Input event is triggered whenever the user interacts with the TextBox by typing, pasting, or using any input method to modify the content. It provides real-time updates as the user enters text, allowing you to perform actions or validation based on the changing input.
It is important to note that the Input event may fire frequently during user input, potentially with each keystroke, so it is generally suitable for handling real-time updates or feedback rather than more intensive processing.
Examples
<SfTextBox Placeholder="Enter a value" Input="@OnInput">
</SfTextBox>
@code{
private void OnInput(InputEventArgs args)
{
var TextValue = args.Value;
}
}InputAttributes
Gets or sets a collection of additional HTML attributes that will be applied directly to the input element of the SfTextBox component.
Declaration
public Dictionary<string, object> InputAttributes { get; set; }Property Value
| Type | Description |
|---|---|
| System.Collections.Generic.Dictionary<System.String, System.Object> | A System.Collections.Generic.Dictionary<, > containing attribute names and values to be applied to the input element. The default value is an empty dictionary. |
Remarks
This property captures unmatched attributes and applies them directly to the HTML input element. Common attributes include:
Attributes can be specified using inline attributes or the @attributes directive.
Note: If you configure both a component property and its equivalent HTML attribute, the component property takes precedence.
Examples
<!-- Using @attributes directive -->
<SfTextBox Placeholder="Enter PIN" @attributes="@inputAttributes">
</SfTextBox>
<!-- Using inline attributes -->
<SfTextBox Placeholder="Enter email" maxlength="50" pattern="[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}$">
</SfTextBox>
@code {
Dictionary<string, object> inputAttributes = new Dictionary<string, object>()
{
{ "maxlength", "4" },
{ "pattern", "[0-9]{4}" },
{ "autocomplete", "one-time-code" }
};
}Multiline
Gets or sets a value indicating whether the SfTextBox operates in multiline mode (textarea).
Declaration
public bool Multiline { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
When multiline mode is enabled, the TextBox transforms into a textarea element that supports:
This mode is particularly useful for capturing longer text content such as comments, descriptions, addresses, or any scenario requiring multi-line input.
Examples
<SfTextBox @bind-Value="@description"
Multiline="true"
Placeholder="Enter your description"
FloatLabelType="FloatLabelType.Auto">
</SfTextBox>
@code {
private string description = "";
}MultilineInput
Declaration
protected override bool MultilineInput { get; set; }Property Value
| Type |
|---|
| System.Boolean |
Overrides
Placeholder
Gets or sets the placeholder text that is displayed when the SfTextBox has no value.
Declaration
public string Placeholder { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | A string representing the placeholder text displayed when the TextBox has no value. The default value is |
Remarks
The placeholder text provides a hint to users about what should be entered in the TextBox.
The behavior of the placeholder depends on the FloatLabelType property:
Examples
<SfTextBox Placeholder="Enter your email address" FloatLabelType="FloatLabelType.Auto"></SfTextBox>Readonly
Gets or sets a value indicating whether the SfTextBox is read-only and prevents user input.
Declaration
public bool Readonly { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
When the TextBox is set to read-only mode, users can view and select the text content but cannot modify it. The component will still participate in form submission and data binding operations.
Examples
<SfTextBox @bind-Value="@readOnlyValue" Readonly="true" Placeholder="Read-only text"></SfTextBox>RootClass
Declaration
protected override string RootClass { get; set; }Property Value
| Type |
|---|
| System.String |
Overrides
ShowClearButton
Gets or sets a value indicating whether the clear button is displayed in the SfTextBox component.
Declaration
public bool ShowClearButton { get; set; }Property Value
| Type | Description |
|---|---|
| System.Boolean |
|
Remarks
The clear button appears when the TextBox has a value and allows users to quickly clear the entire content with a single click. The button is typically displayed as an 'X' icon on the right side of the TextBox.
Examples
<SfTextBox @bind-Value="@textValue" ShowClearButton="true" Placeholder="Enter text"></SfTextBox>TabIndex
Gets or sets the tab order of the SfTextBox component in the tab navigation sequence.
Declaration
public int TabIndex { get; set; }Property Value
| Type | Description |
|---|---|
| System.Int32 | An integer value representing the tab index of the TextBox component. The default value is |
Remarks
The TabIndex property determines the order in which components receive focus when the user navigates using the Tab key.
Examples
<SfTextBox TabIndex="1" Placeholder="First in tab order"></SfTextBox>
<SfTextBox TabIndex="2" Placeholder="Second in tab order"></SfTextBox>Type
Gets or sets the input type behavior of the SfTextBox component, such as text, password, email, and more.
Declaration
public InputType Type { get; set; }Property Value
| Type | Description |
|---|---|
| InputType | One of the InputType enumeration values that specifies the type of input element to render. The default value is Text. |
Remarks
The input type determines the behavior, validation, and appearance of the TextBox:
Different input types may trigger different virtual keyboards on mobile devices and provide built-in browser validation.
Examples
<SfTextBox Type="InputType.Email" Placeholder="Enter your email"></SfTextBox>
<SfTextBox Type="InputType.Password" Placeholder="Enter your password"></SfTextBox>
<SfTextBox Type="InputType.Tel" Placeholder="Enter your phone number"></SfTextBox>ValueChange
Gets or sets the event callback that will be invoked when the content of TextBox has changed and the component loses focus.
Declaration
public EventCallback<ChangedEventArgs> ValueChange { get; set; }Property Value
| Type | Description |
|---|---|
| Microsoft.AspNetCore.Components.EventCallback<ChangedEventArgs> | An Microsoft.AspNetCore.Components.EventCallback<> that is invoked when the TextBox content changes and loses focus. The callback receives a ChangedEventArgs containing the previous and current values. |
Remarks
The ValueChange event is triggered only when the TextBox loses focus and the value has actually changed from its previous state. This differs from the Input event, which fires on every keystroke. Use ValueChange for final value processing, validation, or when you need to compare the old and new values.
Examples
<SfTextBox Placeholder="Enter a value" ValueChange="@OnChange">
</SfTextBox>
@code{
private void OnChange(ChangedEventArgs args)
{
var TextValue = args.Value;
var PreviousValue = args.PreviousValue;
// Process the changed value
}
}Width
Gets or sets the width of the SfTextBox component.
Declaration
public string Width { get; set; }Property Value
| Type | Description |
|---|---|
| System.String | A string representing the width in pixels, percentage, or other CSS units. The default value is |
Remarks
The width can be specified using various CSS units such as pixels (px), percentages (%), em, rem, etc. If not specified, the component will take the full width of its container.
Examples
<SfTextBox Width="300px"></SfTextBox>
<SfTextBox Width="50%"></SfTextBox>
<SfTextBox Width="20rem"></SfTextBox>Methods
AddIconAsync(String, String, Dictionary<String, Object>)
Adds icons to the TextBox component at the specified position.
Declaration
public Task AddIconAsync(string position, string icons, Dictionary<string, object> events = null)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | position | The position where icons should be added, either |
| System.String | icons | The CSS classes representing the icons to be added to the icon element. |
| System.Collections.Generic.Dictionary<System.String, System.Object> | events | The optional dictionary containing icon events that should be added to the events element. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Remarks
This method allows you to dynamically add icons to the TextBox component either before (prepend) or after (append) the input field. The icons parameter accepts CSS class names that define the visual appearance of the icons. When providing events, use the event type as the key and the event handler method as the value in the dictionary.
Examples
The following code demonstrates usage of AddIconAsync(String, String, Dictionary<String, Object>) method through component instance. When passing the Events parameter, 'ontouchstart' denotes the Event type and 'touchStart' denotes the EventHandler method.
Instance.AddIconAsync("prepend", "e-icon-pan", new Dictionary<string, object>() { { "ontouchstart", touchStart } });BuildRenderTree(RenderTreeBuilder)
Declaration
protected override void BuildRenderTree(RenderTreeBuilder __builder)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Rendering.RenderTreeBuilder | __builder |
ChangeHandler(ChangeEventArgs)
Asynchronously handles change events that occur when the input value is modified and committed, typically triggered by focus loss or explicit user actions like Enter key press.
Declaration
protected override Task ChangeHandler(ChangeEventArgs args)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.ChangeEventArgs | args | The Microsoft.AspNetCore.Components.ChangeEventArgs containing the committed input value and event details from the browser's change event. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous change event handling operation. |
Overrides
Remarks
This method processes committed value changes by:
- Extracting the changed value from the event arguments
- Updating the component's CurrentValueAsString property to reflect the new value
- Raising the change event through RaiseChangeEvent with interaction flag set to true
Unlike the InputHandler which fires during real-time typing, the ChangeHandler fires when the value is considered "committed" by the browser, making it suitable for final value processing and validation.
FocusAsync()
Sets the focus to the TextBox component to enable user interaction.
Declaration
public Task FocusAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Remarks
This method programmatically moves the keyboard focus to the TextBox input element, allowing users to immediately start typing. When called, the TextBox will receive focus and display the focus indicator (typically a border highlight or cursor). This is useful for improving user experience by automatically focusing important input fields or implementing custom navigation flows.
FocusHandler(FocusEventArgs)
Asynchronously handles the focus event when the input element receives focus, invoking registered focus event callbacks and providing comprehensive focus event information.
Declaration
protected override Task FocusHandler(FocusEventArgs args)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Web.FocusEventArgs | args | The Microsoft.AspNetCore.Components.Web.FocusEventArgs containing focus event details from the browser's focus event. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous focus event handling operation. |
Overrides
Remarks
This method processes focus events by:
- Creating FocusInEventArgs with current component state and event information
- Invoking the Focus event callback if registered, providing detailed focus context
- Invoking the OnFocus event callback if registered for additional focus handling
The method provides both detailed focus information through FocusInEventArgs and standard focus event args for different use cases and backward compatibility.
FocusOutAsync()
Removes the focus from the TextBox component if it is currently in focus state.
Declaration
public Task FocusOutAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous operation. |
Remarks
This method programmatically removes keyboard focus from the TextBox input element, causing it to blur. When called, the TextBox will lose focus and hide the focus indicator, and any validation or change events may be triggered. This is useful for implementing custom form validation, navigation flows, or when you need to programmatically shift focus to other elements. If the TextBox is not currently focused, this method has no effect.
FocusOutHandler(FocusEventArgs)
Asynchronously handles the focus out (blur) event when the input element loses focus, performing value change detection and invoking registered blur event callbacks.
Declaration
protected override Task FocusOutHandler(FocusEventArgs args)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.Web.FocusEventArgs | args | The Microsoft.AspNetCore.Components.Web.FocusEventArgs containing blur event details from the browser's blur event. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous focus out event handling operation. |
Overrides
Remarks
This method processes blur events by:
- Performing change detection by comparing PreviousValue with current InputTextValue
- Raising change events if the value has been modified since the last change notification
- Creating FocusOutEventArgs with current component state and event information
- Invoking the Blur event callback if registered, providing detailed focus out context
The change detection logic ensures that value changes are properly captured and notified even if they occurred during input without explicit change events being fired.
FormatValue(String)
Formats the specified generic value into a string representation suitable for display in the input element. This method handles null values and ensures type-safe conversion from generic input to string output.
Declaration
protected override string FormatValue(string genericValue)Parameters
| Type | Name | Description |
|---|---|---|
| System.String | genericValue | The generic string value to be formatted. Can be null. |
Returns
| Type | Description |
|---|---|
| System.String | A formatted string representation of the input value, or the default string value if the input is null. |
Overrides
Remarks
This method provides a safe conversion mechanism by:
- Returning the default value (null) when the input value is null
- Using SfBaseUtils.ChangeType for type-safe conversion to string
- Ensuring consistent string formatting across the component
The method is part of the value formatting pipeline and ensures that all values displayed in the TextBox are properly converted to string representation.
GetPersistDataAsync()
Retrieves the properties to be maintained in the persisted state from local storage.
Declaration
public Task<string> GetPersistDataAsync()Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task<System.String> | A System.Threading.Tasks.Task<> containing the persisted data as a JSON string, or null if no data exists. |
Remarks
This method accesses the browser's local storage to retrieve previously saved component state using the component's ID as the key. The persisted data typically includes user-modified properties such as the current value, enabled state, and other configurable settings. This functionality supports the component's state persistence feature, allowing the TextBox to restore its previous state across browser sessions. The returned string should be in JSON format and can be used to restore the component's state using the corresponding persistence methods.
InputHandler(ChangeEventArgs)
Asynchronously handles input events that occur during real-time text entry, providing immediate feedback and event notifications without waiting for focus loss or explicit change events.
Declaration
protected override Task InputHandler(ChangeEventArgs args)Parameters
| Type | Name | Description |
|---|---|---|
| Microsoft.AspNetCore.Components.ChangeEventArgs | args | The Microsoft.AspNetCore.Components.ChangeEventArgs containing the current input value and event details from the browser's input event. |
Returns
| Type | Description |
|---|---|
| System.Threading.Tasks.Task | A System.Threading.Tasks.Task representing the asynchronous input event handling operation. |
Overrides
Remarks
This method processes real-time input events by:
- Creating InputEventArgs with comprehensive input context information
- Providing the current input value and previous value for comparison
- Invoking Input event callbacks if registered for real-time input monitoring
- Updating InputPreviousValue tracking for subsequent change detection
The input handler is essential for features that require real-time feedback, such as character counting, input validation, and dynamic content updates.