LgTextBox

LgTextBox is the text input field: single line, multiline area, password, with optional input mask. The value (a string) binds with @bind-Value.

<LgTextBox Label="#ContactName" @bind-Value="_model.Name" />

Namespace: Lagoon.UI.Components
Inherits from: LgInputRenderBase<string> → LgInputBase<string> → LgAriaComponentBase → LgComponentBase
NuGet package: Lagoon.UI

Specialized variants

LgTextBox serves as the base for several ready-to-use fields: LgSuggestBox (suggestions during input) and LgColorPickerBox (color picker).

Usage

Demo

Try this component in the Lagoon showcase.

Simple input

Placeholder displays hint text, Disabled disables the field, and ReadOnly displays it read-only.

ContactPage.razor
<LgTextBox Label="#ContactName" @bind-Value="_model.Name" />

<LgTextBox Label="#FirstName"
           Placeholder="#TypeYourFirstName"
           Disabled="_isDisabled"
           ReadOnly="_isReadOnly"
           @bind-Value="_model.FirstName" />

ContactPage.razor.cs
public partial class ContactPage : LgPage
{
    // Screen-driven states: disable and read-only the second field.
    private bool _isDisabled;
    private bool _isReadOnly;

    private readonly ContactVm _model = new();

    private sealed class ContactVm
    {
        public string Name { get; set; }
        public string FirstName { get; set; }
    }
}

Password

TextMode="TextBoxMode.Password" masks entered characters.

AccountPage.razor
<LgTextBox Label="#Password"
           TextMode="TextBoxMode.Password"
           @bind-Value="_model.Password" />

AccountPage.razor.cs
public partial class AccountPage : LgPage
{
    private readonly AccountVm _model = new();

    private sealed class AccountVm
    {
        public string Password { get; set; }
    }
}

Multiline area

TextMode="TextBoxMode.Multiline" renders a text area. Rows sets the number of lines, MinRows / MaxRows limit automatic adjustment, and AllowResize allows manual resizing.

CommentPage.razor
<LgTextBox Label="#Comment"
           TextMode="TextBoxMode.Multiline"
           Rows="5"
           MaxLength="500"
           AllowResize="true"
           @bind-Value="_model.Comment" />

CommentPage.razor.cs
public partial class CommentPage : LgPage
{
    private readonly CommentVm _model = new();

    private sealed class CommentVm
    {
        public string Comment { get; set; }
    }
}

Input mask

InputMaskKind chooses the mask type and InputMask the pattern (9: digit, a: letter, *: alphanumeric for the Mask type). InputMaskPlaceholder sets the character that fills still empty positions of the mask (# with the mask 99-99-99-99-99 displays ##-##-##-##-##); without a value, the default character _ is preserved. It must not be confused with Placeholder, which remains the hint text displayed when the field is empty. AutoUnmask returns the value without the mask and ClearIncomplete clears the input if the mask is incomplete.

note

The input mask applies only to plain text mode. It is ignored without error when TextMode equals TextBoxMode.Multiline or TextBoxMode.Password: the mask library targets single-line fields, and a filler character would make no sense on password characters already masked.

PhonePage.razor
<LgTextBox Label="#Phone"
           InputMaskKind="InputMaskKind.Mask"
           InputMask="99 99 99 99 99"
           InputMaskPlaceholder="#"
           Placeholder="#PhoneHint"
           AutoUnmask="true"
           @bind-Value="_model.Phone" />

@* Built-in email input mask. *@
<LgTextBox Label="#Email"
           InputMaskKind="InputMaskKind.Email"
           @bind-Value="_model.Email" />

PhonePage.razor.cs
public partial class PhonePage : LgPage
{
    private readonly PhoneVm _model = new();

    private sealed class PhoneVm
    {
        public string Phone { get; set; }
        public string Email { get; set; }
    }
}

Prefix, suffix, and datalist

Prefix / Suffix display text or an icon in the field. DataList renders an HTML datalist suggesting values during input.

ReferencePage.razor
<LgTextBox Label="#Reference"
           Prefix="REF-"
           PrefixType="InputLabelType.Text"
           DataList="_knownReferences"
           @bind-Value="_model.Reference" />

ReferencePage.razor.cs
public partial class ReferencePage : LgPage
{
    // Values suggested by the browser during input (HTML datalist).
    private readonly List<string> _knownReferences = new() { "1001", "1002", "2001" };

    private readonly ReferenceVm _model = new();

    private sealed class ReferenceVm
    {
        public string Reference { get; set; }
    }
}

Responding to value changes

OnChangingAsync is called before assignment and allows canceling the change (args.Cancel); OnChange is called after. OnInput notifies each keystroke and OnKeyUp each key released. Clearing by the clear button also triggers OnInput, with an empty value (""), like the browser for a search field cleared by its cross button: a filter field that only listens to OnInput therefore does not need to wire OnReset to the same handler. It does not trigger if it is canceled (OnChangingAsync, ConfirmationMessage).

CodePage.razor
<LgTextBox Label="#ProjectCode"
           OnChangingAsync="OnCodeChangingAsync"
           @bind-Value="_model.Code" />

CodePage.razor.cs
public partial class CodePage : LgPage
{
    private readonly CodeVm _model = new();

    // Called before change: refuses reserved codes.
    private Task OnCodeChangingAsync(ChangingEventArgs<string> args)
    {
        if (args.NewValue == "ADMIN")
        {
            args.Cancel = true;
            ShowWarning("#ReservedCode");
        }
        return Task.CompletedTask;
    }

    private sealed class CodeVm
    {
        public string Code { get; set; }
    }
}

Properties

All [Parameter] properties of the component, including inherited ones.

Name	Type	Default	Declared in	Description
`AllowResize`	`bool`	`false`	`LgTextBox`	Allows resizing when `TextMode` equals `TextBoxMode.Multiline`.
`AutoComplete`	`bool`	`false`	`LgTextBox`	Enables browser autocomplete if `true`; otherwise the attribute `autocomplete="off"` is rendered.
`AutoUnmask`	`bool`	`false`	`LgTextBox`	Returns the value without the mask when `InputMask` is used.
`ClearIncomplete`	`bool`	`false`	`LgTextBox`	Clears the value if the input mask is incomplete.
`DataList`	`List<string>`	`null`	`LgTextBox`	List of values used to render a `datalist` associated with the input.
`InputMask`	`string`	`null`	`LgTextBox`	Input mask applied to the text field.
`InputMaskKind`	`InputMaskKind`	`None`	`LgTextBox`	Type of input mask.
`InputMaskPlaceholder`	`string`	`null`	`LgTextBox`	Character filling empty positions of the input mask (for example `#` with the mask `99-99-99-99-99` displays `##-##-##-##-##`). Must not be confused with `Placeholder`. Without a value, the default mask character (`_`) is preserved. Ignored when `InputMaskKind` equals `Regex`.
`MaxLength`	`int?`	`null`	`LgTextBox`	Maximum number of characters. If not defined, it is inferred from the `MaxLength` attribute of the model.
`MaxRows`	`int?`	`null`	`LgTextBox`	Maximum number of lines when `TextMode` equals `TextBoxMode.Multiline`.
`MinRows`	`int?`	`null`	`LgTextBox`	Minimum number of lines when `TextMode` equals `TextBoxMode.Multiline`.
`OnChangeDisabled`	`bool`	`false`	`LgTextBox`	Disables the native `onchange` handler of the field.
`OnChangingAsync`	`Func<ChangingEventArgs<string>, Task>`	`null`	`LgTextBox`	Callback called before value change; the change can be canceled there.
`OnFocus`	`EventCallback<FocusEventArgs>`	—	`LgTextBox`	Callback called when the field receives focus.
`OnInput`	`EventCallback<ChangeEventArgs>`	—	`LgTextBox`	Callback called on input (`oninput`) and when reset by the clear button (value `""`).
`OnKeyUp`	`EventCallback<KeyboardEventArgs>`	—	`LgTextBox`	Callback called when a key is released.
`Placeholder`	`string`	`null`	`LgTextBox`	Hint text displayed when the field is empty. Distinct from `InputMaskPlaceholder`.
`Rows`	`int?`	`null`	`LgTextBox`	Number of lines when `TextMode` equals `TextBoxMode.Multiline`.
`TextMode`	`TextBoxMode?`	`null`	`LgTextBox`	Mode of the text field. `null` renders a simple text field.
`Prefix`	`string`	`null`	`LgInputRenderBase`	Prefix displayed in the field.
`PrefixType`	`InputLabelType`	`Text`	`LgInputRenderBase`	Nature of the prefix.
`Suffix`	`string`	`null`	`LgInputRenderBase`	Suffix displayed in the field.
`SuffixType`	`InputLabelType`	`Text`	`LgInputRenderBase`	Nature of the suffix.
`AdditionalAttributes`	`IReadOnlyDictionary<string, object>`	`null`	`LgInputBase`	Additional HTML attributes applied to the rendered element.
`AutoFocus`	`bool`	`false`	`LgInputBase`	Gives focus to the field on first render.
`ConfirmationMessage`	`string`	`null`	`LgInputBase`	Confirmation message displayed before applying a value change.
`Container`	`IInputContainer<string>`	`null`	`LgInputBase`	Internal use: attaches a GridView cell to the field.
`CssClass`	`string`	`null`	`LgInputBase`	Additional CSS classes.
`Disabled`	`bool`	`false`	`LgInputBase`	Disables the field.
`DisplayName`	`string`	`null`	`LgInputBase`	Name of the field used in error messages.
`HideValidationMessage`	`bool`	`false`	`LgInputBase`	Hides the validation message below the field.
`Label`	`string`	`null`	`LgInputBase`	Field label.
`LabelContent`	`RenderFragment`	`null`	`LgInputBase`	Custom content of the label area.
`OnChange`	`EventCallback<ChangeEventArgs>`	—	`LgInputBase`	Callback called after value change.
`OnReset`	`EventCallback<ChangeEventArgs>`	—	`LgInputBase`	Callback called when the field is reset by the clear button.
`PolicyEdit`	`string`	`null`	`LgInputBase`	Policy required to edit the field.
`PolicyVisible`	`string`	`null`	`LgInputBase`	Policy required to display the field.
`ReadOnly`	`bool`	`false`	`LgInputBase`	Displays the field read-only.
`Required`	`bool?`	`null`	`LgInputBase`	Required field. If `null`, inferred from the `[Required]` attribute of the bound property.
`ResetButton`	`bool?`	`null`	`LgInputBase`	Displays the clear button. If `null`, the application's behavior configuration applies.
`ResetText`	`string`	`null`	`LgInputBase`	Text of the clear button.
`ResetTextAriaLabel`	`string`	`null`	`LgInputBase`	Accessible label (`aria-label`) of the clear button.
`Tooltip`	`string`	`null`	`LgInputBase`	Tooltip.
`TooltipIsHtml`	`bool`	`false`	`LgInputBase`	Indicates whether the content of the `Tooltip` is in HTML format (otherwise plain text).
`Value`	`string`	`null`	`LgInputBase`	Bound value (`@bind-Value`).
`ValueChanged`	`EventCallback<string>`	—	`LgInputBase`	Callback for updating the bound value.
`ValueExpression`	`Expression<Func<string>>`	—	`LgInputBase`	Expression identifying the bound property.
`AriaLabel`	`string`	`null`	`LgAriaComponentBase`	Value of the `aria-label` attribute.
`AriaLabelledBy`	`string`	`null`	`LgAriaComponentBase`	Value of the `aria-labelledby` attribute.

Cascading parameters

LgTextBox also consumes parameters automatically provided by ancestor components (you do not need to define them): ParentAuthorizeView (LgAuthorizeView) and the editing context of a parent LgEditForm.

Events

Event	Type	Description
`OnChangingAsync`	`Func<ChangingEventArgs<string>, Task>`	Before value change; `args.Cancel = true` cancels the change.
`OnChange`	`EventCallback<ChangeEventArgs>`	After value change.
`OnInput`	`EventCallback<ChangeEventArgs>`	On each field content modification, including reset by the clear button (value `""`, unless the reset is canceled).
`OnKeyUp`	`EventCallback<KeyboardEventArgs>`	When a key is released in the field.
`OnFocus`	`EventCallback<FocusEventArgs>`	When the field receives focus.
`OnReset`	`EventCallback<ChangeEventArgs>`	When reset by the clear button.

Associated enumerations

`TextBoxMode`

Rendering mode of the field (property TextMode; null renders a simple text field).

Value	Description
`Multiline`	Renders a multiline text area.
`Password`	Renders a password field.

`InputMaskKind`

Type of input mask (property InputMaskKind).

Value	Description
`None`	No mask (default value).
`Mask`	Mask based on `9` (digit), `a` (letter), and `*` (alphanumeric).
`Regex`	Regex-based mask.
`Email`	Email input mask.

Best practices / accessibility

Provide Label (or AriaLabel): the label carries the field's accessibility and the required field indicator.
MaxLength is inferred from the MaxLength attribute of the model: set the constraint on the view model rather than hardcoded in the markup.
For long text edited in a modal, prefer LgSummaryBox.

Complete reference

All parameters (including inherited ones): API reference — LgTextBox.

LgSuggestBox — input with suggestions.
LgColorPickerBox — color picker based on LgTextBox.
LgSummaryBox — long text edited in a modal.
LgTagBox — list of text values as tags.

Usage​

Demo​

Simple input​

Password​

Multiline area​

Input mask​

Prefix, suffix, and datalist​

Responding to value changes​

Properties​

Events​

Associated enumerations​

TextBoxMode​

InputMaskKind​

Best practices / accessibility​

Related components​