TextField

The everyday configurations of a text field. Label renders the caption above the input and is what a screen reader announces, so it is preferred over relying on Placeholder alone: a placeholder disappears the moment the first character is typed. Description adds a permanent hint under the field and is wired to the input through aria-describedby. IsEnabled="false" takes the field out of the tab order entirely, while ReadOnly keeps it focusable and copyable but refuses edits. Required renders the html required attribute and marks the label with an asterisk, MaxLength and MinLength map to the html length constraints, AutoFocus puts the caret in the field on the first render, and FullWidth makes the field fill the width of its container instead of sizing to its content.

The underlined variant drops the box around the field and keeps only the bottom rule, which is the denser look used in toolbars and inline editing. The label moves next to the input instead of above it, and the focus indicator becomes a thicker underline. Everything else - placeholder, disabled and required rendering - behaves exactly as in the default variant.

NoBorder removes the frame around the field so it blends into the surface behind it, which is what a text field embedded in a card, a table cell or a custom composite control usually wants. The field keeps its focus ring, so keyboard users can still tell where they are.

Multiline renders a textarea instead of an input. Rows sets its height, Resizable gives back the native resize grip that is hidden by default, and AutoHeight grows the field with its content so no scrollbar ever shows up. The two work together: Rows stays the floor of that growth, so a field asking for four rows does not collapse to a single line the moment its value is emptied. MaxRows puts a ceiling on it: past that many rows the field stops growing and scrolls internally, which is what keeps a long paste from pushing the rest of the page off screen. The height is measured again whenever the field itself changes width - a narrowed window, a panel folding away - since the same text takes a different number of lines once it re-wraps. PreventEnter stops the Enter key from inserting a new line - handy when Enter should submit the surrounding form - while Shift+Enter still adds one. Wrap passes through to the html attribute of the same name: off turns the wrapping off entirely and scrolls long lines sideways, which is what a field holding code or log lines wants, and hard makes the breaks the wrapping adds travel with the submitted value.

Type maps to the html type of the input, which decides what the browser does with the value: the password type masks it, the number type accepts floating-point syntax - digits, a decimal separator, a sign and the scientific notation - and reports anything else as invalid instead of refusing every non-digit character, the email and url types validate the format on submit, and the search type lets the browser offer the previous searches of the same field. InputMode is independent of it and only decides which virtual keyboard a phone brings up, so a text field asking for a PIN can still show the numeric keypad. EnterKeyHint relabels the return key of that keyboard, and Pattern, SpellCheck, AutoCorrect and AutoCapitalize pass through to the matching html attributes. The number type here is only the html one - the value is still bound as a string and there is no bound, no step and no spinner: a field that really holds a number wants BitNumberField, which binds any .NET numeric type and brings the clamping, the stepping and the spinbutton keyboard set with it.

IconName renders an icon of the built-in Fluent UI set at the trailing end of the field. It is decorative by default - hidden from screen readers and not focusable - so it should reinforce the label rather than replace it; an icon that does carry a meaning of its own gets a name of its own through IconAriaLabel, shown in the Accessibility section. The icon picks up the Accent color while the field has focus, and goes grey along with the rest of the field while it is disabled.

A prefix and a suffix are static pieces of text rendered inside the frame of the field, before and after the input. They are not part of the value: a field with the https:// prefix still binds only what was typed. Because of that, keep a descriptive label on the field, since a screen reader reads the value without the affixes around it.

Every piece of chrome around the input can be replaced by a template when the plain string parameters are not enough: LabelTemplate, DescriptionTemplate, PrefixTemplate and SuffixTemplate take over from Label, Description, Prefix and Suffix, ClearButtonTemplate replaces the icon of the clear button, RevealPasswordTemplate receives whether the password is currently revealed, CountTemplate receives the current number of characters, ErrorMessageTemplate replaces the rejection message under the field and marks it invalid just like the plain ErrorMessage does, and LoadingTemplate replaces the spinner of the busy indicator (shown in the Loading section). A field rendered through a LabelTemplate still gets the required asterisk, so custom chrome never costs the field its markings.

Type="BitInputType.Password" masks the value. Adding CanRevealPassword renders a toggle button that swaps the input to plain text, which is the pattern that lets people check what they typed instead of typing the password twice. The button keeps one stable RevealPasswordAriaLabel in both states and reports the current state through aria-pressed, which is what screen readers announce reliably; the caret is handed back to the input after every toggle. RevealPasswordIconName and HidePasswordIconName customize the two icons, and the native reveal affordance that Edge and Internet Explorer add to a password input is taken away so that only one of them is ever shown. The ToggleRevealPassword method drives the same toggle from the outside - from a checkbox next to the form, for instance - and is ignored unless the field is a revealable password, so a revealed value can never survive the reveal being taken away. Pair the field with an AutoComplete of current-password or new-password: it is what tells a password manager whether to offer the saved credentials or to generate a new one, and it is the difference between a sign-in form that fills itself and one that fights the browser.

ShowClearButton renders a button that empties the field, and it only appears while there is something to clear - from the very first keystroke, since it follows what the input holds rather than the bound value, which on a field without Immediate is only committed on blur. Clearing sets the value to null through the normal binding, fires OnClear and returns the focus to the input so typing can continue right away. The button is a real button with an ClearButtonAriaLabel, so it is reachable by keyboard, and it is disabled in the read-only and disabled states. ClearButtonIconName swaps its icon, and it works in the multiline mode too. A search input draws a clear affordance of its own in WebKit browsers, which is hidden while the clear button is on so that the field never shows two of them. The ClearAsync method does the same thing from code - without needing the button to be visible at all - and raises OnClear just like a click on it does.

ShowCount renders a counter under the field. With a MaxLength it reads typed/limit and is pointed at by aria-describedby, so a screen reader announces the limit along with the field; without one it is just the number of characters typed so far. The counter follows the keystrokes directly rather than the bound value, so it stays live even when Immediate is off and the value is only committed on blur. CountTemplate replaces the whole text with content of its own, shown in the Templates section. A count above the limit turns red: the keyboard cannot get there, since MaxLength renders the html maxlength attribute, but a value assigned from the code can, and a counter reading a number above its own limit in the muted grey of a valid one would say nothing about it.

By default the characters are counted the way the browser counts them against the limit - in UTF-16 code units - which makes an emoji count as two and a family emoji as eleven. CountStrategy replaces that with a count of your own, most often StringInfo.LengthInTextElements, which counts what a reader actually sees. It only changes the number that is shown: the maxlength attribute keeps holding the keyboard back at its own count, so a strategy that counts fewer characters than the browser does reaches the limit before the counter says so.

The value is committed on the change event by default, which for a text field means when it loses focus. Immediate switches to the input event so every keystroke updates the bound value; on top of it, DebounceTime waits until the typing pauses for that many milliseconds before committing, and ThrottleTime commits at most once per that many milliseconds - both of them are what a search-as-you-type field wants so it does not fire a request per character. DefaultValue seeds an uncontrolled field that reports through OnChange instead of a two-way binding. An Immediate field also guards against the input method editors used for Chinese, Japanese and Korean: the half-composed characters a candidate window produces are kept out of the bound value, which only receives the text once the composition is committed.

Ghost text is the faded completion an editor shows after what has been typed. Set GhostText from the outside - from an autocomplete list, from a model, from anywhere - and it is painted behind the input without ever entering the value. Pressing Tab or Enter with the caret at the end of the text, or clicking/touching the field there, accepts it: the text is inserted, the bound value is updated whether or not Immediate is on, and OnGhostTextAccepted fires with the accepted string so the suggestion can be cleared or replaced. Any other keystroke discards the suggestion, and a suggestion that would not fit under MaxLength is cut down to whatever room is left rather than pushing the value past the limit the keyboard cannot pass either. PermanentGhost reserves the scrollbar gutter of a multiline field so the text does not shift when the suggestion makes it overflow. The overlay itself is painted for the eye only and hidden from screen readers, so the suggestion is announced through a polite live region instead - without it an inline completion would be a feature only sighted users ever learn about.

Trim strips the leading and trailing whitespace off the value, which is what keeps a stray space from being saved along with an email address or a coupon code. It is applied when the input reports a change - not on every keystroke - so a space can still be typed in the middle of a word while Immediate is on. Note that it does not touch a DefaultValue, which is assigned to the value as it is given.

[]

[]

Besides OnChange, the field forwards the raw dom events it sits on: OnKeyDown and OnKeyUp for every key, OnEnter and OnEscape as shortcuts for the two keys a form cares about most, OnClick, and OnFocus, OnBlur, OnFocusIn and OnFocusOut for the focus lifecycle. The difference between the two pairs is bubbling: focus and blur are raised by the input alone, while focusin and focusout also reach it from whatever is inside it, which is what makes them the ones to watch when a whole group of controls is being tracked. All of them are skipped while the field is disabled. OnEnter and OnEscape are also skipped while an input method editor is composing, where the two keys commit and cancel a candidate rather than the value - so a form is never submitted in the middle of typing a Chinese or Japanese word.

OnInput is the one that fires on every input event, whichever way the text arrived - a keystroke, a paste, a drop, an autofill - which is what a strength meter or a live preview needs. Unlike OnChange it does not wait for the field to lose focus and it does not require Immediate, so it can watch the text without committing it, and it is raised before DebounceTime and ThrottleTime hold the value back rather than along with it. Like the rest of the events it stays quiet while an input method editor is composing, so it never sees a half-composed word.

SelectOnFocus selects the whole value the moment the field receives focus, so the next keystroke replaces it instead of appending to it - what a field holding a value meant to be overwritten rather than edited (a search term, a quantity, a generated code) usually wants. It applies to a read-only field too, where selecting the value is exactly what makes it easy to copy, and to an AutoFocus field, whose focus is given to it before anything could listen for it. The same thing is available from code through SelectAsync, and SelectRangeAsync selects only a part of the value, or moves the caret when the two positions are equal. Both positions are clamped to the length of the value, a null start counts from the beginning and a null end runs to the very end, so a range can never fall outside the text.

LabelPosition moves the label around the input: Top is the classic form layout, Bottom puts the caption under the field, and Start and End lay the two out on one line, which is what a compact settings row or a filter bar wants. The two row layouts follow the reading direction rather than the screen, so they mirror themselves in a right-to-left page. Leaving the parameter unset keeps the layout each variant comes with - above the input in the default one and next to it in the underlined one - so an existing field never moves on its own.

Loading shows a busy indicator inside the field, which is how a field says that something is running against what was typed - a suggestion being fetched, a name being checked for availability, a value being validated on the server. The field stays fully editable while it is on, so the typing is never interrupted. The input carries aria-busy while it is on, which is what tells an assistive technology that what it is reading is still being worked on, and a polite live region that is always part of the field announces that it started - politely, so it waits for the reader to finish the sentence it is on rather than cutting into it. LoadingAriaLabel is what that announcement says instead of the default "Loading", and LoadingTemplate replaces the spinner with any content - one of the other loading components of the library, an icon, a piece of text - without costing the field its announcement.

A field is only usable by everyone when what it expects is exposed to assistive technologies as well as to the eye. Label is the first tool for that and should be preferred over AriaLabel, which names the input for a screen reader without showing anything - use it only where the surrounding layout already makes the purpose obvious. Setting both is allowed and the AriaLabel wins: the visible caption keeps labelling the field for the eye and for the click that focuses it, while the screen reader is given the fuller name. Description is the visible hint under the field, while AriaDescription is a hidden one for the cases where the instruction would be too long to show; both are referenced by the input through aria-describedby, in reading order, alongside the error message that comes first when there is one and the character counter when it carries a limit. An aria-describedby of your own, passed through InputHtmlAttributes, is kept and read first rather than replaced, which is what lets a field point at an error message the app renders next to it and still keep its own description. Title renders the html title of the field, which the browser shows as a tooltip on hover. The trailing icon is decorative and hidden from screen readers by default; IconAriaLabel turns it into an image with a name for the cases where the icon carries a meaning of its own.

Inside an EditForm the field joins the cascading EditContext automatically, so the data annotations on the model drive it: a failing field gets the bit-inv class and the aria-invalid="true" attribute, and the state is refreshed on every validation pass. Use NoValidate to opt a field out of the EditContext altogether, and DisplayName to control the name used in the generated messages.

Not every rejection comes from a data annotation, though - a name a server reports as taken, a rule that needs two fields to be compared, a field that lives outside any form at all. Invalid forces the same state from the outside: the same red frame, the same focus ring and the same aria-invalid, without an EditContext being involved. It only ever adds to the validation of the field, so a value the EditContext already rejected stays invalid whatever the parameter says.

ErrorMessage is what turns that red frame into something the reader can act on: the text is rendered under the field, above the description and the counter, and setting it marks the field invalid on its own - there is no need to also set Invalid. It is referenced by the input through aria-describedby ahead of the description, and announced by the live region of the field the moment it shows up, so a rejection that arrives while the field still has focus is not something only sighted users learn about. ErrorMessageTemplate replaces the text with content of its own, shown in the Templates section. Both are meant for the rejections the app knows about; inside an EditForm the messages of the data annotations belong to the ValidationMessage component instead, so the same text is not printed twice.

Background picks the fill of the field from the color kinds of the theme. Transparent is the one to use when the field sits on a colored surface and should inherit it instead of punching a light rectangle into it.

Border picks the color of the frame from the same color kinds, independently of the background. Transparent keeps the border box - and therefore the layout - while making the line itself invisible, which is the difference between it and NoBorder.

Accent is the color the field takes on while it has focus: the focus ring, the icon and the affixes all follow it. Primary is the default, and the remaining variants are what gives a field a meaning of its own - a success green on a confirmed value, an error red on a rejected one - without touching the rest of the theme.

The Icon parameter takes a BitIconInfo instead of a built-in icon name, which is what lets an icon come from FontAwesome, Bootstrap Icons or any other icon font: BitIconInfo.Fa and BitIconInfo.Bi build the class names of those two libraries, BitIconInfo.Css takes the classes verbatim, and a plain string is implicitly converted to one. The same applies to ClearButtonIcon, RevealPasswordIcon and HidePasswordIcon.

Size scales the whole field at once - its height, its font, its icons and its buttons - so a field stays proportional to the controls next to it. Medium is the default; Small is what a dense toolbar or a table row wants, and Large is what a landing page form wants.

Style and Class land on the root element, while Styles and Classes reach every inner part by name - the label, the field group, the input, the buttons, the footer and the counter - which is what makes a fully custom look possible without overriding the stylesheet. Focused is applied to the root only while the field has focus, so a floating label can be driven entirely from these two parameters.

Set Dir="BitDir.Rtl" to mirror the field for a right-to-left language. The label, the affixes, the buttons, the required asterisk and the underline all follow the direction, since the layout is written with logical properties rather than left and right ones.