Skip to content
# TextField **Also known as:** TextInput, TextArea, PasswordField ## Description Text fields give people a way to enter and edit text. They're used in forms, modal dialogs, tables, and other surfaces where text input is required. A single BitTextField renders either an input or a textarea, carries a label in any of the four positions around it, a visible or screen-reader-only description, a character counter and a message saying why the value was rejected, exposes every part of its chrome to templates and to the Styles and Classes parameters, wires its own labels and descriptions to the input through the aria attributes, and plugs into an EditForm the same way the built-in Blazor inputs do. ## Parameters | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Accent | `BitColor?` | null | The general color of the text field used when focused. An explicit value wins over the --bit-TextField-* accent and focus color variables (and over --bit-TextField-button-color for the reveal password glyph and --bit-TextField-spinner-color for the busy spinner); left unset, the accent is primary unless they say otherwise. | | AriaDescription | `string?` | null | Detailed description of the input for the benefit of screen readers. It is rendered into a visually hidden element that the input references through its aria-describedby attribute, which is what lets a field carry an instruction that would be too long to show next to it. | | AutoCapitalize | `string?` | null | Sets the autocapitalize html attribute of the input element, which tells the on-screen keyboard of a mobile device whether and how the typed text should be capitalized automatically. Accepted values are "off", "none", "on", "sentences", "words" and "characters". | | AutoCorrect | `bool?` | null | Sets the autocorrect html attribute of the input element, which turns the automatic correction of the typed text on or off. Useful to turn off for identifiers, codes and other non-prose values. | | AutoHeight | `bool` | false | Automatically adjust the height of the input in Multiline mode. | | Background | `BitColorKind?` | null | The color kind of the text field background. An explicit value wins over --bit-TextField-background; left unset, the background is the primary kind unless it says otherwise. --bit-TextField-hover-background still paints the hovered fill, since no kind has one of its own. | | Border | `BitColorKind?` | null | The color kind of the text field border. An explicit value wins over --bit-TextField-border-color and --bit-TextField-hover-border-color; left unset, the border is the primary kind unless they say otherwise. --bit-TextField-focus-border-color still paints the focused frame, since no kind has a focus color of its own. | | CanRevealPassword | `bool` | false | Whether to show the reveal password button for input type 'password'. | | Classes | `BitTextFieldClassStyles?` | null | Custom CSS classes for different parts of the BitTextField. | | ClearButtonAriaLabel | `string?` | null | The aria-label of the clear button, which is what a screen reader announces for it since the button only holds an icon. Defaults to "Clear text". | | ClearButtonIcon | `BitIconInfo?` | null | The icon to display inside the clear button. Takes precedence over ClearButtonIconName when both are set. | | ClearButtonIconName | `string?` | Cancel | Gets or sets the name of the icon to display on the clear button from the built-in Fluent UI icons. | | ClearButtonTemplate | `RenderFragment?` | null | The custom content of the clear button, which replaces its icon. | | ClearedAnnouncement | `string?` | null | What a screen reader announces once the field has been emptied - by the clear button or by ClearAsync - in place of the default "Cleared". Emptying a field moves nothing and says nothing on its own, so without it the one interaction that throws the whole value away is the one a screen reader user gets no confirmation of. Set it to an empty string to keep the clearing from being announced at all. | | ClearOnEscape | `bool` | false | Empties the field when the Escape key is pressed in it, which is the keyboard counterpart of the clear button and what a filter or a search field is expected to do. It raises OnClear and is announced the same way a press on the button is, it leaves a read-only field and one bound one way alone, and it does not need ShowClearButton. The press that clears the field is the field's alone, so a Dialog, a Modal, a Panel or an Overlay around it closes on the next one; an Escape with Shift, Ctrl, Alt or Meta held clears nothing and goes straight to them. OnEscape is still raised afterwards, and Escape keeps its own meaning while an input method editor is composing. | | CountStrategy | `Func<string?, int>?` | null | Decides how the characters of the value are counted for the counter rendered by ShowCount. Leaving it unset counts the value the way the browser counts it against MaxLength - in UTF-16 code units - which makes an emoji count as two and a flag as four. A strategy of its own counts them the way the rest of the app does instead, for instance v => new StringInfo(v ?? string.Empty).LengthInTextElements to count what a reader actually sees. It only changes the number that is shown: the html maxlength attribute keeps holding the keyboard back at its own count. | | CountTemplate | `RenderFragment<int>?` | null | The custom content of the character counter, which receives the current number of characters and replaces the default "count/maxLength" text. | | Description | `string?` | null | Description displayed below the text field to provide additional details about what text to enter. | | DescriptionTemplate | `RenderFragment?` | null | Shows the custom description for text field. | | EnterKeyHint | `string?` | null | Sets the enterkeyhint html attribute of the input element, which decides the label of the return key of an on-screen keyboard. Accepted values are "enter", "done", "go", "next", "previous", "search" and "send". | | ErrorMessage | `string?` | null | The message shown under the field when the value was rejected. Setting it marks the field invalid on its own - the same look and the same aria-invalid attribute Invalid gives it - and the message is referenced by the input through its aria-describedby attribute and announced by the live region of the field. | | ErrorMessageAriaLabel | `string?` | null | The text a screen reader is given for a rejection that has no text of its own: an ErrorMessageTemplate, which is free to render anything at all, or the forced Invalid state. It is announced through the live region the moment the rejection shows up - in place of the default "Invalid input" for a template, and only when it is set for the forced state - and the input references it through aria-describedby, so the same reason is read out on every later focus too. A plain ErrorMessage is its own text and never uses it. Give it the reason the template shows, in the language of the page: a template switching to another reason is only announced again when this text switches along with it. Cascaded through BitParams it reaches every text field under it, so set it there only as a generic replacement for "Invalid input". | | ErrorMessageTemplate | `RenderFragment?` | null | The custom content of the error message, which replaces the plain ErrorMessage text and marks the field invalid in the same way. It replaces the message for a screen reader as well: a template is free to render anything at all, so the live region announces ErrorMessageAriaLabel for it, or a bare "Invalid input" when that is not set. | | FullWidth | `bool` | false | Forces the text field fill 100% of its container width. | | GhostText | `string?` | null | The ghost/suggestion text displayed inline after the current cursor position. Update this value from outside (e.g. from an AI or autocomplete suggestion) to show a faded inline suggestion. The user can accept it by pressing Tab or Enter, or clicking/touching the ghost text. | | HidePasswordIcon | `BitIconInfo?` | null | Gets or sets the icon for the reveal password button when password is shown using custom CSS classes for external icon libraries. | | HidePasswordIconName | `string?` | null | The icon name for the reveal password button when password is shown from the built-in Fluent UI icons. | | Icon | `BitIconInfo?` | null | Gets or sets the icon to display using custom CSS classes for external icon libraries. Takes precedence over IconName when both are set. | | IconAriaLabel | `string?` | null | The accessible name of the icon shown inside the text field. The icon is decorative and hidden from assistive technologies by default; setting this turns it into an image with a name, which is what an icon carrying a meaning of its own needs. | | IconName | `string?` | null | The icon name for the icon shown inside the text field, at the end IconPlacement puts it at, from the built-in Fluent UI icons. | | IconPlacement | `BitPlacement?` | null | Which end of the field the icon sits at, inside the frame. End (the default) puts it past the clear and reveal buttons, Start in front of the input. It follows the reading direction, so it mirrors itself in a right-to-left page. | | IconTitle | `string?` | null | The html title of the icon shown inside the text field, which the browser shows as its tooltip. It is only rendered while OnIconClick makes the icon a button, since a tooltip on a decorative mark says something only a pointer ever finds. | | InputMode | `BitInputMode?` | null | Sets the inputmode html attribute of the input element. | | Invalid | `bool` | false | Marks the value of the field as invalid, which gives a value rejected by something other than the cascading EditContext - a server, a rule of the app, a validator of its own - the same look and the same aria-invalid attribute that a failing data annotation gives it. A field failing its own validation stays invalid regardless of this parameter. It says nothing more to a screen reader unless ErrorMessageAriaLabel gives it a reason to announce. | | Label | `string?` | null | Label displayed above the text field and read by screen readers. | | LabelPlacement | `BitPlacement?` | null | Where the label sits relative to the input. Leaving it unset keeps the layout each variant comes with: above the input in the default one, and next to it in the Underlined one. Only Top, Bottom, Start and End are honoured; any other value leaves the layout as it is with this unset. | | LabelTemplate | `RenderFragment?` | null | Shows the custom label for text field. | | Loading | `bool` | false | Shows a busy indicator inside the field, which is what tells the user that something is running against what was typed - a suggestion being fetched, a value being checked against a server. The field stays editable while it is on, so the typing is never interrupted by it. | | LoadingAriaLabel | `string?` | null | What a screen reader announces while Loading is on, in place of the default "Loading". It is announced whichever indicator is drawn, so a LoadingTemplate drawing a bare spinner of its own still tells an assistive technology that something is running. | | LoadingTemplate | `RenderFragment?` | null | The custom content of the busy indicator, which replaces the default spinner. | | MaxLength | `int` | -1 | Specifies the maximum number of characters allowed in the input. A negative value (the default) removes the limit and renders no maxlength attribute. | | MaxRows | `int?` | null | The maximum number of rows the input grows to in the Multiline mode while AutoHeight is enabled. Beyond that height the input keeps its size and scrolls its content instead of pushing the rest of the page down. A null value (the default) lets the input grow indefinitely. | | MinLength | `int` | -1 | Specifies the minimum number of characters the input accepts, which is what the browser validates the value against before the form is submitted. A negative value (the default) removes the constraint and renders no minlength attribute. | | Multiline | `bool` | false | Whether or not the text field is a Multiline text field. | | NoBorder | `bool` | false | Removes the border of the text input. | | OnBlur | `EventCallback<FocusEventArgs>` | | Callback for when the input loses focus. Unlike OnFocusOut it does not bubble, so it is the one to use when only the input itself losing focus is of interest. | | OnClear | `EventCallback` | | Callback executed when the user clears the text field by clicking the clear button. | | OnClick | `EventCallback<MouseEventArgs>` | | Callback for when the input clicked. | | OnEnter | `EventCallback<KeyboardEventArgs>` | | Callback for when the Enter key is pressed while input has focus. | | OnEscape | `EventCallback<KeyboardEventArgs>` | | Callback for when the Escape key is pressed while input has focus. | | OnFocus | `EventCallback<FocusEventArgs>` | | Callback for when the input receives focus. Unlike OnFocusIn it does not bubble, so it is the one to use when only the input itself receiving focus is of interest. | | OnFocusIn | `EventCallback<FocusEventArgs>` | | Callback for when focus moves into the input or any of its descendants, since unlike OnFocus it bubbles. | | OnFocusOut | `EventCallback<FocusEventArgs>` | | Callback for when focus moves out of the input or any of its descendants, since unlike OnBlur it bubbles. | | OnGhostTextAccepted | `EventCallback<string?>` | | Callback invoked when the ghost text is accepted via Tab or Enter key, or click/touch. The accepted ghost text string is passed as the argument. | | OnIconClick | `EventCallback<MouseEventArgs>` | | Callback for when the icon inside the field is clicked, which is what turns the icon into an action - opening a picker, copying the value, running a search - instead of a mark that only says what the field is for. Giving it a handler renders the icon as a real button: it takes a tab stop, answers Enter and Space, draws a focus ring of its own and is named by IconAriaLabel, so give that one a value whenever this one has a handler. | | OnInput | `EventCallback<ChangeEventArgs>` | | Callback for every input event of the input element, which is what lets a field watch the text as it is typed without having to turn Immediate on and commit the value along with it. It is raised before the value is committed and is not held back by DebounceTime or ThrottleTime, and it is not raised for the half-composed text of an input method editor. | | OnKeyDown | `EventCallback<KeyboardEventArgs>` | | Callback for when a keyboard key is pressed. | | OnKeyUp | `EventCallback<KeyboardEventArgs>` | | Callback for When a keyboard key is released. | | Pattern | `string?` | null | Sets the pattern html attribute of the input element, which is the regular expression the value is checked against by the browser before the form is submitted. | | PermanentGhost | `bool` | false | Enables permanent ghost mode that forces the scrollbar-gutter to always be present, preventing layout shift of the ghost text rendering. | | Placeholder | `string?` | null | Input placeholder text. | | Prefix | `string?` | null | Prefix displayed before the text field contents. This is not included in the value. Ensure a descriptive label is present to assist screen readers, as the value does not include the prefix. | | PrefixTemplate | `RenderFragment?` | null | Shows the custom prefix for text field. | | PreventEnter | `bool` | false | Prevents the enter to add new line character into the input in the Multiline mode. | | Resizable | `bool` | false | For multiline text fields, whether or not the field is resizable. Vertically only: a width dragged past the frame around it would leave the input hanging out of its own field. AutoHeight takes the grip away again, since the height is then the content's to decide. | | RevealPasswordAriaLabel | `string?` | null | Aria label for the reveal password button. It stays the same in both states on purpose: the pressed state of the button is what tells a screen reader whether the password is currently revealed. Defaults to "Reveal password". | | RevealPasswordIcon | `BitIconInfo?` | null | Gets or sets the icon for the reveal password button when password is hidden using custom CSS classes for external icon libraries. | | RevealPasswordIconName | `string?` | null | The icon name for the reveal password button when password is hidden from the built-in Fluent UI icons. | | RevealPasswordTemplate | `RenderFragment<bool>?` | null | The custom content of the reveal password button, which receives whether the password is currently revealed and replaces the default icon. | | Rows | `int?` | null | For multiline text, Number of rows. | | SelectOnFocus | `bool` | false | Selects the whole value when the input receives focus, so that the next keystroke replaces it. It is what a field holding a value the user is expected to overwrite rather than edit - a search term, a quantity, a generated code - usually wants. | | ShowClearButton | `bool` | false | Whether to show the clear button while the input holds any text. The button follows what the input reports rather than the bound value, so it is there from the first keystroke even on a field that only commits its value when it loses focus. | | ShowCount | `bool` | false | Shows the number of characters that were typed under the text field, followed by the MaxLength when one is set. A count above the limit - only reachable from the code, since the maxlength attribute holds the keyboard back - is colored like a rejected value. | | Size | `BitSize?` | null | The size of the text field. An explicit value wins over the --bit-TextField-* size variables (minimum height, font sizes, line height, icon size, spinner size, button width); left unset, the field is medium unless they say otherwise. | | SpellCheck | `bool?` | null | Sets the spellcheck html attribute of the input element, which turns the spell checking of the browser on or off for this input. | | Styles | `BitTextFieldClassStyles?` | null | Custom CSS styles for different parts of the BitTextField. | | Suffix | `string?` | null | Suffix displayed after the text field contents. This is not included in the value. Ensure a descriptive label is present to assist screen readers, as the value does not include the suffix. | | SuffixTemplate | `RenderFragment?` | null | Shows the custom suffix for text field. | | Title | `string?` | null | A more descriptive title of the text field, shown by the browser as its tooltip. It is written on the frame, so the tooltip also covers the affixes and the icon around the input, and on the input itself, so it reaches a keyboard and an assistive technology. | | Trim | `bool` | false | Specifies whether to remove any leading or trailing whitespace from the value. The trimming happens when the input reports a change, which is what lets a space still be typed in the middle of a word while Immediate is enabled. | | Type | `BitInputType?` | null | Input type. | | Underlined | `bool` | false | Whether or not the text field is underlined. The label then sits on the row of the input, takes at most half of it and is cut short with an ellipsis when it is longer, with the whole text offered as its tooltip; a LabelPlacement of Top, Bottom, Start or End moves it off that row and lets it wrap again. | | Wrap | `string?` | null | Sets the wrap html attribute of the textarea rendered in the Multiline mode, which decides how the text is wrapped and whether the breaks the wrapping adds travel with the value when a form is submitted. Accepted values are "soft" (what a browser does on its own), "hard" and "off", the last of which turns the wrapping off entirely and scrolls long lines sideways instead. | | AutoComplete | `string?` | null | Specifies the value of the autocomplete attribute of the input component. | | AutoFocus | `bool` | false | Determines if the text input is auto focused on first render. | | DebounceTime | `int` | 0 | The debounce time in milliseconds. | | Immediate | `bool` | false | Change the content of the input field when the user write text (based on 'oninput' HTML event). | | ThrottleTime | `int` | 0 | The throttle time in milliseconds. | | DefaultValue | `TValue?` | null | The default value of the input to be used in uncontrolled mode (i.e. when the Value is not bound), typically used alongside the OnChange callback. | | DisplayName | `string?` | null | Gets or sets the display name for this field. | | InputHtmlAttributes | `IReadOnlyDictionary<string, object>?` | null | Gets or sets a collection of additional attributes that will be applied to the created element. | | Name | `string?` | null | Gets or sets the name of the element. Allows access by name from the associated form. | | NoValidate | `bool` | false | Disables the validation of the input. | | OnChange | `EventCallback<TValue?>` | | Callback for when the input value changes. | | ReadOnly | `bool` | false | Makes the input read-only. | | Required | `bool` | false | Makes the input required. | | Value | `TValue?` | null | Gets or sets the value of the input. This should be used with two-way binding. | | AriaLabel | `string?` | null | Gets or sets the accessible label for the component, used by assistive technologies. | | Class | `string?` | null | Gets or sets the CSS class name(s) to apply to the rendered element. | | Dir | `BitDir?` | null | Gets or sets the text directionality for the component's content. | | Disabled | `bool` | false | Gets or sets a value indicating whether the component is disabled and cannot respond to user interaction. | | ForceAnimation | `bool` | false | Gets or sets a value indicating whether the component's animations play at their full duration even when reduced motion is requested. | | HtmlAttributes | `Dictionary<string, object>` | new Dictionary<string, object>() | Captures additional HTML attributes to be applied to the rendered element, in addition to the component's parameters. An attribute written on the component wins over an entry of the same name. | | Id | `string?` | null | Gets or sets the unique identifier for the component's root element. | | Style | `string?` | null | Gets or sets the CSS style string to apply to the rendered element. | | TabIndex | `string?` | null | Gets or sets the tab order index for the component when navigating with the keyboard. | | Visibility | `BitVisibility` | BitVisibility.Visible | Gets or sets the visibility state (visible, hidden, or collapsed) of the component. | ## Public Members | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | InputElement | `ElementReference` | | The ElementReference to the input element of the BitTextField. | | ClearAsync | `Task` | | Empties the text field and raises OnClear, exactly as the clear button does (without requiring ShowClearButton, since there is no button involved). It does nothing while the field is disabled or read-only. | | FocusAsync | `ValueTask` | | Gives focus to the input element of the BitTextField. The overload taking a preventScroll flag focuses it without scrolling the document to bring it into view. | | SelectAsync | `ValueTask` | | Selects the whole value of the input, the programmatic counterpart of SelectOnFocus. | | SelectRangeAsync | `ValueTask` | | Selects the text between the two given positions, or moves the caret when they are equal. A null start counts from the beginning of the value and a null end runs to its very end, and both are clamped to the length of the value. | | ToggleRevealPassword | `void` | | Toggles the revealed state of the value while the type of the input is password and CanRevealPassword is enabled. | | InputElement | `ElementReference` | | The ElementReference of the input element. | | FocusAsync() | `() => ValueTask` | | Gives focus to the input element. | | FocusAsync(bool preventScroll) | `(bool preventScroll) => ValueTask` | | Gives focus to the input element. | | UniqueId | `Guid` | Guid.NewGuid() | Gets the readonly unique identifier for the component's root element, assigned when the component instance is constructed. | | RootElement | `ElementReference` | | Gets the reference to the root HTML element associated with this component. | ## Enums ### BitColor Enum | Name | Value | Description | | :--- | :--- | :---------- | | Primary | 0 | Primary general color. | | Secondary | 1 | Secondary general color. | | Tertiary | 2 | Tertiary general color. | | Info | 3 | Info general color. | | Success | 4 | Success general color. | | Warning | 5 | Warning general color. | | SevereWarning | 6 | SevereWarning general color. | | Error | 7 | Error general color. | | PrimaryBackground | 8 | Primary background color. | | SecondaryBackground | 9 | Secondary background color. | | TertiaryBackground | 10 | Tertiary background color. | | PrimaryForeground | 11 | Primary foreground color. | | SecondaryForeground | 12 | Secondary foreground color. | | TertiaryForeground | 13 | Tertiary foreground color. | | PrimaryBorder | 14 | Primary border color. | | SecondaryBorder | 15 | Secondary border color. | | TertiaryBorder | 16 | Tertiary border color. | ### BitColorKind Enum | Name | Value | Description | | :--- | :--- | :---------- | | Primary | 0 | The primary color kind. | | Secondary | 1 | The secondary color kind. | | Tertiary | 2 | The tertiary color kind. | | Transparent | 3 | The transparent color kind. | ### BitPlacement Enum | Name | Value | Description | | :--- | :--- | :---------- | | Top | 0 | The top edge. | | Bottom | 1 | The bottom edge. | | Start | 2 | The edge the reading direction starts from - the left in LTR, the right in RTL. On the vertical axis, which does not turn around, it is the top. | | End | 3 | The edge the reading direction ends at - the right in LTR, the left in RTL. On the vertical axis, which does not turn around, it is the bottom. | | Left | 4 | The left edge, in both reading directions. | | Right | 5 | The right edge, in both reading directions. | | Center | 6 | The middle of the axis, against neither edge. | | TopAndBottom | 7 | Both edges of the block axis at once. | | StartAndEnd | 8 | Both edges of the inline axis at once, following the reading direction the way Start and End do. | ### BitSize Enum | Name | Value | Description | | :--- | :--- | :---------- | | Small | 0 | The small size. | | Medium | 1 | The medium size. | | Large | 2 | The large size. | ### BitInputType Enum | Name | Value | Description | | :--- | :--- | :---------- | | Text | 0 | The input expects text characters. | | Password | 1 | The input expects password characters. | | Number | 2 | The input expects number characters. | | Email | 3 | The input expects email characters. | | Tel | 4 | The input expects tel characters. | | Url | 5 | The input expects url characters. | | Search | 6 | The input expects a search term, which is what lets a browser offer the previous searches of the same field and show its own clear affordance. | ### BitInputMode Enum | Name | Value | Description | | :--- | :--- | :---------- | | None | 0 | No virtual keyboard. For when the page implements its own keyboard input control. | | Text | 1 | Standard input keyboard for the user's current locale. | | Decimal | 2 | Fractional numeric input keyboard containing the digits and decimal separator for the user's locale. | | Numeric | 3 | Numeric input keyboard, but only requires the digits 0–9. | | Tel | 4 | A telephone keypad input, including the digits 0–9, the asterisk (*), and the pound (#) key. | | Search | 5 | A virtual keyboard optimized for search input. | | Email | 6 | A virtual keyboard optimized for entering email addresses. | | Url | 7 | A keypad optimized for entering URLs. | ### BitVisibility Enum | Name | Value | Description | | :--- | :--- | :---------- | | Visible | 0 | The content of the component is visible. | | Hidden | 1 | The content of the component is hidden, but the space it takes on the page remains (visibility:hidden). | | Collapsed | 2 | The component is hidden (display:none). | ### BitDir Enum | Name | Value | Description | | :--- | :--- | :---------- | | Ltr | 0 | Ltr (left to right) is to be used for languages that are written from the left to the right (like English). | | Rtl | 1 | Rtl (right to left) is to be used for languages that are written from the right to the left (like Arabic). | | Auto | 2 | Auto lets the user agent decide. It uses a basic algorithm as it parses the characters inside the element until it finds a character with a strong directionality, then applies that directionality to the whole element. | ## Sub Classes ### BitTextFieldClassStyles Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Root | `string?` | null | Custom CSS classes/styles for the BitTextField's root element. | | Focused | `string?` | null | Custom CSS classes/styles of the root element in focus state. | | InputWrapper | `string?` | null | Custom CSS classes/styles for the wrapper of label and input in the BitTextField. | | Label | `string?` | null | Custom CSS classes/styles for the BitTextField's label. | | FieldGroup | `string?` | null | Custom CSS classes/styles for the BitTextField's field group. | | PrefixContainer | `string?` | null | Custom CSS classes/styles for the BitTextField's prefix container. | | Prefix | `string?` | null | Custom CSS classes/styles for the BitTextField's prefix. | | Input | `string?` | null | Custom CSS classes/styles for the BitTextField's input. | | Loading | `string?` | null | Custom CSS classes/styles for the BitTextField's busy indicator container. | | Spinner | `string?` | null | Custom CSS classes/styles for the BitTextField's default busy spinner, drawn when no LoadingTemplate is set. | | RevealPassword | `string?` | null | Custom CSS classes/styles for the BitTextField's reveal password. | | RevealPasswordIconContainer | `string?` | null | Custom CSS classes/styles for the BitTextField's reveal password icon container. | | RevealPasswordIcon | `string?` | null | Custom CSS classes/styles for the BitTextField's reveal password icon. | | ClearButton | `string?` | null | Custom CSS classes/styles for the BitTextField's clear button. | | ClearButtonIcon | `string?` | null | Custom CSS classes/styles for the BitTextField's clear button icon. | | Icon | `string?` | null | Custom CSS classes/styles for the BitTextField's icon. | | IconButton | `string?` | null | Custom CSS classes/styles for the button the BitTextField's icon is wrapped in while it has an OnIconClick handler. | | SuffixContainer | `string?` | null | Custom CSS classes/styles for the BitTextField's suffix container. | | Suffix | `string?` | null | Custom CSS classes/styles for the BitTextField's suffix. | | ErrorMessageContainer | `string?` | null | Custom CSS classes/styles for the BitTextField's error message container. | | ErrorMessage | `string?` | null | Custom CSS classes/styles for the BitTextField's error message. | | Footer | `string?` | null | Custom CSS classes/styles for the BitTextField's footer, which holds the description and the character counter. | | DescriptionContainer | `string?` | null | Custom CSS classes/styles for the BitTextField's description container. | | Description | `string?` | null | Custom CSS classes/styles for the BitTextField's description. | | Count | `string?` | null | Custom CSS classes/styles for the BitTextField's character counter. | | GhostTextWrapper | `string?` | null | Custom CSS classes/styles for the BitTextField's ghost text wrapper element. | | GhostTextOverlay | `string?` | null | Custom CSS classes/styles for the BitTextField's ghost text overlay container. | ### BitIconInfo Properties | Name | Type | Default Value | Description | | :--- | :--- | :------------ | :---------- | | Name | `string?` | null | Gets or sets the name of the icon. | | BaseClass | `string?` | null | Gets or sets the base CSS class for the icon. For built-in Fluent UI icons, this defaults to "bit-icon". For external icon libraries like FontAwesome, you might set this to "fa" or leave empty. | | Prefix | `string?` | null | Gets or sets the CSS class prefix used before the icon name. For built-in Fluent UI icons, this defaults to "bit-icon--". For external icon libraries, you might set this to "fa-" or leave empty. | ## CSS Variables Public CSS custom properties read off the component's root. Set one on `:root` to restyle every instance, on any ancestor to restyle the ones inside it, or on the `Style` of one instance to restyle it and every instance nested inside it, which inherits the value too - a parameter changes one alone, as does the real CSS property on its `Style` / `Styles` when that property does not inherit (`opacity`); an inherited one (`color`, `font-family`) reaches the nested instances that do not set it themselves. | Name | Default Value | Description | | :--- | :------------ | :---------- | | `--bit-TextField-background` | --bit-clr-bg-pri | Fill of the frame at rest. It is also what is painted over the background Chrome forces onto an autofilled field. The Background parameter wins over it. | | `--bit-TextField-hover-background` | The rest fill | Fill of the frame while the pointer is over it. Unchanged from the rest fill by default, since the frame color is what moves on hover. No Background kind has a hover fill of its own, so it applies under an explicit Background too. | | `--bit-TextField-border-color` | --bit-clr-brd-pri | Color of the frame, and of the bottom rule of the Underlined variant, at rest. The Border parameter wins over it. | | `--bit-TextField-hover-border-color` | --bit-clr-brd-pri-hover | Color of the frame while the pointer is over it. Drawn on pointer devices only, and never over the focused or the rejected frame. The Border parameter wins over it with its kind's own hover step (transparent for the Transparent kind). | | `--bit-TextField-focus-border-color` | The rest frame color | Color of the frame while the field has focus. Unset by default - the focus ring is the indicator this design system draws - and there for a design system whose fields color their border instead. A rejected value keeps its own frame color regardless. No Border kind has a focus color of its own, so it applies under an explicit Border too. | | `--bit-TextField-invalid-border-color` | --bit-clr-err | Color of the frame of a rejected value, whether it was rejected by the EditContext, by Invalid or by an ErrorMessage. | | `--bit-TextField-focus-color` | --bit-clr-pri-focus | Color of the keyboard focus ring, of the underline of a focused Underlined field, and of the rings of the clear, reveal and icon buttons. The Accent parameter wins over it. While it is unset, the focus ring is the library's own --bit-shd-focus-ring, so replacing that token re-shapes it too. | | `--bit-TextField-invalid-focus-color` | --bit-clr-err-focus | Focus ring color of a rejected value. | | `--bit-TextField-accent-color` | --bit-clr-pri | Color the trailing icon, the prefix, the suffix and the busy indicator take while the field has focus, and the resting color of the reveal password glyph. The Accent parameter wins over it. | | `--bit-TextField-border-width` | --bit-shp-brd-width | Thickness of the frame and of the bottom rule of the Underlined variant. | | `--bit-TextField-radius` | --bit-shp-radius-control | Corner radius of the frame, which its focus ring follows. The parts at the ends of the frame - the prefix, the suffix, the input (and the cover over an autofilled value) and the clear, reveal and icon buttons - take their corners from the frame itself, so a radius given to it through Styles.FieldGroup or Classes.FieldGroup reshapes them too. A part shaped through its own Classes keeps the shape it was given; an end a PrefixTemplate or SuffixTemplate holds is left to the template. | | `--bit-TextField-shadow` | none | Elevation of the frame, for a field drawn as a raised surface rather than an outlined one. | | `--bit-TextField-min-height` | --bit-siz-ctrl-md | Smallest height of the frame, which is what lines a field up with the other controls of its size. It is a floor, not a height: a multiline field still grows with its content. The Size parameter wins over it. | | `--bit-TextField-transition-duration` | --bit-mot-duration-short | How long the frame takes to repaint between the rest, hover and focus colors. It collapses to near zero under prefers-reduced-motion unless ForceAnimation is set. | | `--bit-TextField-color` | --bit-clr-fg-pri | Color of the typed text, and the fill color handed to an autofilled field. | | `--bit-TextField-caret-color` | --bit-TextField-color | Color of the text cursor. | | `--bit-TextField-placeholder-color` | --bit-clr-fg-sec | Color of the placeholder. It replaces the grey the browser picks on its own, which is not derived from the theme and drops below the contrast floor on most surfaces. | | `--bit-TextField-font-family` | --bit-tpg-font-family | Typeface of the field and of its chrome, for a field holding code or a monospaced identifier. | | `--bit-TextField-font-size` | --bit-tpg-fs-sm | Size of the typed text, the affixes, and the label when it has no size of its own. The Size parameter wins over it. | | `--bit-TextField-font-weight` | --bit-tpg-fw-regular | Weight of the typed text. | | `--bit-TextField-line-height` | spacing(2.125) | Leading of the multiline text and of the ghost overlay behind it. It is also what AutoHeight measures the rows against, so changing it changes how tall Rows and MaxRows make the field. The Size parameter wins over it. | | `--bit-TextField-padding` | 0 spacing(1), and spacing(0.75) spacing(1) when Multiline | Padding of the input inside the frame, which the ghost overlay follows so the suggestion stays lined up with the text. | | `--bit-TextField-resize` | vertical | The axes the grip of a Resizable multiline field drags along. Vertical only by default: a width dragged past the frame around it would leave the input hanging out of its own field. | | `--bit-TextField-label-color` | --bit-clr-fg-pri | Color of the label. | | `--bit-TextField-label-font-size` | --bit-TextField-font-size | Size of the label. The Size parameter wins over it. | | `--bit-TextField-label-font-weight` | --bit-tpg-field-label-font-weight | Weight of the label. | | `--bit-TextField-label-letter-spacing` | --bit-tpg-ctrl-letter-spacing | Tracking of the label, which follows the global control tracking so a field matches the buttons next to it. | | `--bit-TextField-label-gap` | spacing(1) | Room between the label and the frame when the two share a row, which is the Start and End label positions. | | `--bit-TextField-required-color` | --bit-clr-req | Color of the asterisk marking a required field. | | `--bit-TextField-icon-color` | --bit-clr-fg-pri | Color of the icon at rest, whether it is a decorative glyph or the button an OnIconClick makes of it. While the field has focus the icon takes the accent color instead. | | `--bit-TextField-icon-size` | --bit-siz-icon-md | Size of the icon and of the glyphs of the clear and reveal password buttons. The Size parameter wins over it. | | `--bit-TextField-spinner-size` | --bit-siz-icon-md plus the spinner stroke on each side | Diameter of the default busy spinner. The Size parameter wins over it. | | `--bit-TextField-spinner-color` | The busy indicator's color (see --bit-TextField-accent-color) | Color of the moving arc of the default busy spinner. The Accent parameter wins over it, and a disabled field greys it regardless. | | `--bit-TextField-spinner-track-color` | The arc color at 25% | Color of the ring the arc of the default busy spinner travels on. | | `--bit-TextField-button-width` | --bit-siz-ctrl-md | Width of the clear, reveal password and clickable icon buttons, which is what keeps them above the 24px minimum pointer target of WCAG 2.2. The Size parameter wins over it. | | `--bit-TextField-button-color` | --bit-clr-fg-sec for the clear button, the accent color for the reveal one | Glyph color of the clear and reveal password buttons at rest. The Accent parameter wins over it for the reveal glyph. | | `--bit-TextField-button-hover-color` | --bit-clr-fg-pri-hover | Glyph color of the clear button and of a clickable icon while they are hovered. | | `--bit-TextField-button-hover-background` | --bit-clr-bg-pri-hover | Background of the clear, reveal password and clickable icon buttons while they are hovered. | | `--bit-TextField-affix-color` | --bit-clr-fg-pri | Color of the prefix and the suffix at rest. While the field has focus both take the accent color instead. | | `--bit-TextField-affix-background` | --bit-clr-bg-sec, none in the Underlined variant | Fill behind the prefix and the suffix, which is what sets them apart from the input between them. The underlined variant has no box to fill against, so it leaves the affixes unfilled unless this is set. | | `--bit-TextField-affix-padding` | 0 spacing(1.25) | Padding of the prefix and the suffix. | | `--bit-TextField-description-color` | --bit-clr-fg-pri | Color of the description under the field. | | `--bit-TextField-count-color` | --bit-clr-fg-sec | Color of the character counter while it is within the limit. | | `--bit-TextField-error-color` | --bit-clr-err | Color of the message under a rejected value, and of a counter that is over its limit. | | `--bit-TextField-footer-font-size` | --bit-tpg-fs-2xs | Size of the description, the counter and the error message. | | `--bit-TextField-footer-gap` | spacing(0.625) | Room between the frame and what is written under it - the error message, the description and the counter - which is the same air the label leaves above the frame. | | `--bit-TextField-ghost-color` | --bit-clr-fg-ter | Color of the inline ghost suggestion painted behind the input. | | `--bit-TextField-disabled-color` | --bit-clr-fg-dis | Text, label, icon, affix and counter color while the field is disabled. | | `--bit-TextField-disabled-background` | --bit-clr-bg-dis | Fill of the frame while the field is disabled. | | `--bit-TextField-disabled-border-color` | --bit-clr-brd-dis | Frame color while the field is disabled. | ## Examples \n**Basics**: ```razor ``` \n**Variants**: ```razor ``` \n**Multiline**: ```razor ``` \n**Input type**: ```razor ``` \n**Icon & affixes**: ```razor
The icon was pressed [@iconClickCount] times.
``` ```csharp private int iconClickCount; ``` \n**Password**: ```razor ToggleRevealPassword ``` ```csharp private BitTextField? passwordRef; ``` \n**Binding**: ```razor
Value: [@oneWayValue]
Value: [@twoWayValue]
Value: [@onChangeValue]
Value: [@defaultValueChanged]
Value: [@immediateValue]
Value: [@debounceValue]
Value: [@throttleValue]
[@trimmedValue]
[@notTrimmedValue]
``` ```csharp private string? oneWayValue; private string? twoWayValue; private string? onChangeValue; private string? defaultValueChanged; private string? immediateValue; private string? debounceValue; private string? throttleValue; private string? trimmedValue; private string? notTrimmedValue; ``` \n**Clear button**: ```razor ClearAsync
Value: [@clearApiValue]
``` ```csharp private BitTextField? clearRef; private string? clearApiValue = "Clear me from the button below"; ``` \n**Character count**: ```razor
Value: [@countValue]
``` ```csharp private string? countValue; private static int CountTextElements(string? value) => new StringInfo(value ?? string.Empty).LengthInTextElements; ``` \n**Templates**: ```razor Custom Label Custom Label of a required field Description Prefix Suffix ✕ @(isRevealed ? "hide" : "show") @count of 20 characters ✖ This name is reserved. See the Validation section. ``` \n**GhostText**: ```razor
Value: [@ghostBasicTextValue]
Value: [@ghostBasicMultilineValue]
Value: [@ghostTextValue]
Value: [@ghostMultilineValue]
``` ```csharp private string? ghostBasicTextValue; private string? ghostBasicSuggestion; private string? ghostBasicMultilineValue; private string? ghostBasicMultilineSuggestion; private string? ghostTextValue; private string? ghostSuggestion; private string? ghostMultilineValue; private string? ghostMultilineSuggestion; private CancellationTokenSource? _ghostSuggestionCts; private CancellationTokenSource? _ghostMultilineSuggestionCts; private static readonly string[] _suggestions = [ "application form", "banana smoothie", "car repair manual", "dog training guide" ]; private static string? GetGhostSuggestion(string? value) { if (string.IsNullOrEmpty(value)) return null; if (char.IsWhiteSpace(value[^1])) return null; var lastWord = value.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries).LastOrDefault(); if (string.IsNullOrEmpty(lastWord)) return null; var match = _suggestions.FirstOrDefault(s => s.StartsWith(lastWord, StringComparison.OrdinalIgnoreCase)); return match?[lastWord.Length..]; } private async Task SetGhostSuggestionAsync(string? value, bool isMultiline) { var cts = new CancellationTokenSource(); if (isMultiline) { CancelAndDispose(ref _ghostMultilineSuggestionCts); _ghostMultilineSuggestionCts = cts; ghostMultilineSuggestion = null; } else { CancelAndDispose(ref _ghostSuggestionCts); _ghostSuggestionCts = cts; ghostSuggestion = null; } try { var suggestion = await GetGhostSuggestionAsync(value, cts.Token); if (cts.IsCancellationRequested) return; if (isMultiline) { ghostMultilineSuggestion = suggestion; } else { ghostSuggestion = suggestion; } } catch (OperationCanceledException) { } } private void ClearGhostSuggestion(bool isMultiline) { if (isMultiline) { CancelAndDispose(ref _ghostMultilineSuggestionCts); ghostMultilineSuggestion = null; } else { CancelAndDispose(ref _ghostSuggestionCts); ghostSuggestion = null; } } private static void CancelAndDispose(ref CancellationTokenSource? cts) { cts?.Cancel(); cts?.Dispose(); cts = null; } private static async Task GetGhostSuggestionAsync(string? value, CancellationToken cancellationToken) { await Task.Delay(300, cancellationToken); return GetGhostSuggestion(value); } ``` \n**Events**: ```razor
Last event: [@eventLog]
Last key down: [@lastKey]
Last key up: [@lastKeyUp]
Focus: [@focusLog]
Typed so far: [@onInputText]
Committed value: [@onInputCommittedValue]
OnClear: [@clearLog]
``` ```csharp private int eventCount; private int clearCount; private string? eventLog; private string? lastKey; private string? lastKeyUp; private string? focusLog; private string? clearLog; private void HandleOnEnter() => eventLog = $"OnEnter ({++eventCount})"; private void HandleOnEscape() => eventLog = $"OnEscape ({++eventCount})"; private void HandleOnKeyDown(KeyboardEventArgs e) => lastKey = e.Key; private void HandleOnKeyUp(KeyboardEventArgs e) => lastKeyUp = e.Key; private void HandleOnClick() => eventLog = $"OnClick ({++eventCount})"; private void HandleOnFocus() => focusLog = "focused"; private void HandleOnBlur() => focusLog = "blurred"; private void HandleOnFocusIn() => focusLog = "focused in"; private void HandleOnFocusOut() => focusLog = "focused out"; private void HandleOnClear() => clearLog = $"cleared ({++clearCount})"; private string? onInputText; private string? onInputCommittedValue; private void HandleOnInput(ChangeEventArgs e) => onInputText = e.Value?.ToString(); ``` \n**Selection**: ```razor SelectAsync SelectRangeAsync(4, 12) Caret to the start ``` ```csharp private BitTextField? selectionRef; ``` \n**Label position**: ```razor ``` \n**Loading**: ```razor ``` ```csharp private string? userName; private bool userNameLoading; private string? userNameStatus; private CancellationTokenSource? _userNameCts; private async Task CheckUserNameAsync(string? value) { CancelAndDispose(ref _userNameCts); if (string.IsNullOrWhiteSpace(value)) { userNameLoading = false; userNameStatus = null; return; } var cts = new CancellationTokenSource(); _userNameCts = cts; userNameLoading = true; userNameStatus = null; try { await Task.Delay(1500, cts.Token); userNameStatus = value.Length < 5 ? $"'{value}' is already taken." : $"'{value}' is available."; } catch (OperationCanceledException) { return; } finally { if (cts.IsCancellationRequested is false) { userNameLoading = false; } } } private static void CancelAndDispose(ref CancellationTokenSource? cts) { cts?.Cancel(); cts?.Dispose(); cts = null; } ``` \n**Accessibility**: ```razor
The field also points at this element, which is not a part of it.
Shipping address
``` \n**Validation**: ```razor Submit ``` ```csharp public class ValidationTextFieldModel { [Required(ErrorMessage = "This field is required.")] public string Text { get; set; } [RegularExpression("0*[1-9][0-9]*", ErrorMessage = "Only numeric values are allowed.")] public string NumericText { get; set; } [RegularExpression("^[a-zA-Z0-9.]*$", ErrorMessage = "Only letters(a-z), numbers(0-9), and period(.) are allowed.")] public string CharacterText { get; set; } [EmailAddress(ErrorMessage = "Invalid e-mail address.")] public string EmailText { get; set; } [StringLength(5, MinimumLength = 3, ErrorMessage = "The text length must be between 3 and 5 chars.")] public string RangeText { get; set; } } private string? invalidValue = "no-space-here"; private string? errorMessageValue = "not-an-email"; private string? EmailError => errorMessageValue.HasValue() && errorMessageValue!.Contains('@') is false ? $"'{errorMessageValue}' is not an email address." : null; private ValidationTextFieldModel validationTextFieldModel = new(); private void HandleValidSubmit() { } private void HandleInvalidSubmit() { } ``` \n**Cascading parameters**: ```razor ``` ```csharp private readonly BitTextFieldParams[] textFieldParams = [ new() { Trim = true, Underlined = true, ShowClearButton = true, Placeholder = "Enter a text...", } ]; ``` \n**Background**: ```razor ``` \n**Border**: ```razor ``` \n**Accent**: ```razor ``` \n**External Icons**: ```razor ``` \n**Size**: ```razor ``` \n**Style & Class**: ```razor
``` ```csharp private string? classesValue; ``` \n**RTL**: ```razor ```