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. Disabled 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.

Three frames for the same field. The default draws a box around the input. Underlined drops the box and keeps only the bottom rule - the denser look of a toolbar or an inline edit - and moves the label next to the input instead of above it. NoBorder takes the frame away entirely, so the field blends into the surface behind it: a card, a table cell, a composite control of your own. All three keep the focus ring, so a keyboard user can always tell where they are, and all three render the required and disabled states the same way.

Multiline renders a textarea instead of an input. Rows sets its height, Resizable gives back the native resize grip that is hidden by default - vertically only, since a width dragged past the frame would leave the input hanging out of its own field - 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.

An icon and the two affixes - a prefix and a suffix - sit inside the frame beside the input. IconName renders a glyph of the built-in Fluent UI set, and IconPlacement decides which end it takes: End by default, past the clear and reveal buttons, or Start in front of the input, where the mark that says what a field is for belongs. Prefix and Suffix are static pieces of text on either side and are not part of the value - a field with an https:// prefix still binds only what was typed - so keep a descriptive label on the field, since a screen reader reads the value without the affixes around it.

All three follow the reading direction rather than the screen, so they mirror themselves in a right-to-left page. The icon is decorative by default - hidden from screen readers and not focusable - and one that carries a meaning of its own gets a name through IconAriaLabel, shown in the Accessibility section. It picks up the Accent color while the field has focus, and the whole frame shows a text cursor and means it: a press on an affix, on the icon or on the busy indicator puts the caret in the input.

OnIconClick turns the icon into an action instead - opening a picker, copying the value, running a search. Giving it a handler renders the icon as a real button: it takes a tab stop, answers Enter and Space and draws a focus ring of its own, so pair it with an IconAriaLabel that says what pressing it does, and with an IconTitle for the tooltip. It keeps working on a read-only field, since an action the icon stands for is not an edit, and it is disabled along with the field.

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.

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.

Trim strips the leading and trailing whitespace off whatever is committed, which is what keeps a stray space from being saved along with an email address or a coupon code. It runs on the change event rather than on every keystroke, so a space can still be typed in the middle of a word while Immediate is on, and it leaves a DefaultValue alone, since that one is assigned as it is given.

Whatever the field ends up holding is what is left on screen: a trimmed value, and the old value of a Value bound without a ValueChanged or an OnChange, are both written back into the input, so the text under the caret is never something the field is not actually holding.

[]

[]

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. Emptying a field moves nothing and says nothing on its own, so the field announces it through its live region - ClearedAnnouncement is what that announcement says instead of the default "Cleared", and an empty string keeps it silent. ClearOnEscape puts the same clearing on the Escape key, which is what a filter or a search field is expected to do; it needs no button of its own, leaves a read-only field alone, and lets Escape keep its meaning while an input method editor is composing. 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.

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.

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. What the region says is the suggestion and nothing else, so pair the field with an AriaDescription saying how to take it ("press Tab to accept the suggestion").

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.

LabelPlacement 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. An aria-labelledby of your own is kept the same way and names the field instead of the visible label, which is what a field labelled by a heading or a table column header needs. 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. The placeholder is painted from the theme rather than left to the grey the browser picks, which fails the contrast floor on a dark surface - but it still disappears the moment anything is typed, so it never carries what the Label and the Description should.

The field keeps one polite live region of its own, which is what carries the things that happen away from the caret: a rejection that arrives while the field still has focus, the busy state, an inline suggestion, and the emptying of the field by the clear button - ClearedAnnouncement is what that last one says. They are announced politely, so none of them ever cuts into what is being read. AutoComplete is what says which piece of personal information a field collects, which a browser, a password manager and an assistive technology all read; a field asking for a name, an address, an email or a credential wants one (WCAG 2.2, Identify Input Purpose).

In Windows High Contrast the whole palette collapses to the system pair, which would take four of the states of the field with it: the disabled field is redrawn in the system grey, the rejected frame becomes a dashed one rather than a red one, the ghost suggestion keeps reading as a suggestion instead of as text already in the value, and a field that deliberately has no frame is given one back, since there is nothing else left to say where it is.

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.

BitParams carries a BitTextFieldParams down to every text field under it, so a form, a panel or a whole app sets the shared look and the shared input behavior once instead of on every field. What it carries is a default and not an override: a field that writes a parameter for itself keeps its own value, and only what it left unset is filled in from the cascade.

Three groups of parameters are deliberately not on the params object, because sharing them between fields would be wrong rather than merely unused: what identifies a field and carries its value (Value, DefaultValue, Name, DisplayName), the event callbacks, and what says something about the value in one field alone (Invalid, ErrorMessage, GhostText, Loading, AutoFocus). InputHtmlAttributes and NoValidate stay out too, as they do for every input: the first is a dictionary the field writes into, and the second is read before a cascade is applied.

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. Each kind carries its own hover step, so the frame darkens under the pointer without leaving the kind it was given, and a Transparent one stays invisible. The hover is drawn on pointer devices only, and never over a focused or a rejected frame.

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.

For the look rather than the layout there are the public --bit-TextField-* custom properties listed in the CSS variables table. They are read off the element and inherited, so the same name set on :root re-skins every field of the app, set on an ancestor re-skins the fields inside it, and set on the Style of one field re-skins that one alone - without a selector, a scoped stylesheet or a ::deep anywhere. Anything left unset keeps the value the theme gives it, so a single property can be swapped without restating the rest.

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.