NumberField

The essential configurations of the BitNumberField: a plain field, a disabled field carrying a default value, a placeholder that shows before any value is entered, and a required field. The TValue type parameter selects the numeric type of the field (it is inferred automatically when a value is bound); with a nullable type the field can also be genuinely empty, which is what you want whenever "no value yet" is different from zero. By default focusing the field selects its whole text for a quick overwrite; NoSelectOnFocus disables that. The value is committed when the field loses focus or on Enter, and it is parsed with the invariant culture, tolerating whitespace between digit groups so that a number pasted from a spreadsheet or a web page still lands correctly. Anything that is not a number is rejected and reported through the standard validation channel (see the Validation section), rather than silently discarded. The field is rendered as an ARIA spinbutton and supports the full keyboard set of that pattern out of the box: Up/Down arrows step by the Step, PageUp/PageDown by a larger jump, and Home/End go to the Min/Max.

The label of the BitNumberField can be positioned on any side of the input using the LabelPosition parameter, and can be fully customized (with any markup or components) using the LabelTemplate.

The Description parameter renders a hint under the field - the accepted range, the unit, the reason the value matters - which is where a user looks before typing rather than after being told they got it wrong. It is not merely decorative: the input references it through aria-describedby, so a screen reader announces it together with the field and its label, and the hint reaches everybody rather than only the people who can see it. Use DescriptionTemplate when the hint needs markup or components of its own. AriaDescription is the complementary parameter - it adds an explanation for assistive technologies only, rendered into a visually hidden element - and the two can be combined, the input then referencing both in reading order.

The Mode parameter decides how the increment/decrement buttons render: Compact stacks them at the end of the input, Inline puts them side by side at the end, and Spread puts one on each side with the value centered between them - the classic quantity picker. When Mode is left unset no buttons render at all, and the value is changed by typing, by the arrow keys or by the wheel. Holding a button down spins the value continuously (see the Step section for the timing parameters), and clicking one keeps the caret in the input, so the keyboard can take over from where the mouse left off. The buttons are decorated with IncrementIconName and DecrementIconName, and given hover tooltips with IncrementTitle and DecrementTitle. A separate IconName renders a decorative icon inside the field itself - give it an IconAriaLabel when it carries meaning, otherwise it is hidden from screen readers.

Three parameters adjust the frame the field is drawn in, without touching anything it does. Underlined replaces the full border with a single bottom rule (the focus indicator follows suit and becomes a thicker rule rather than a ring), which suits dense forms and inline editing. NoBorder removes the border altogether - the right choice inside a surface that already provides one, such as a toolbar, a table cell or a card. FullWidth stretches the field to fill its container, which matters when it sits inside a flex or grid layout that would otherwise size it to its content.

Enabling ShowClearButton renders a clear (X) button inside the field whenever it is showing something, resetting the value to null with a single click. It follows what is actually in the input rather than just the bound value, so it also appears for text that failed to parse and needs wiping, and it disappears again as soon as the field is empty - including when the value is taken away from the outside. It is most useful with nullable value types, since only those can genuinely hold "no value". The button stays out of the tab order, keeping the input the single tab stop; Escape is the keyboard equivalent of clicking it. Its icon comes from ClearButtonIconName (or ClearButtonIcon for an external icon set) and its accessible name from ClearButtonAriaLabel. It is never rendered on a read-only field.

The NumberFormat parameter formats the displayed value using standard or custom .NET numeric format strings, such as N0 (thousands grouping), C0 (currency), or a custom mask like 000000 (zero padding). The formatting is a display concern only: the bound value always stays a plain number, and while the field is being edited the plain number is what you see, so you never have to type around a currency symbol, a grouping separator or a run of padding zeros. The formatted rendering comes back as soon as the field loses focus. Typing a formatted number is accepted too - the separators and symbols of the current culture are stripped before parsing, including the parentheses that accounting formats use for negative amounts. Note that value-scaling formats such as the percent P format (which multiplies the displayed number by 100) are not suitable, since the scaled text cannot be parsed back into the same value.

Static text can be rendered before and after the input using the Prefix and Suffix parameters, which is how a unit ("km", "%") or a currency symbol is attached to a field without becoming part of what the user has to type: these adornments are visual only, never part of the bound value and never part of what gets parsed. That also means a screen reader announcing the value will not mention them, so keep the Label (or a Description) carrying the unit as well. When plain text is not enough - an icon, a button, a currency picker - PrefixTemplate and SuffixTemplate replace the adornment with arbitrary markup, in which case the surrounding container and its styling are yours to provide too.

The value can be bound one-way (the field only reflects the source and its edits are discarded on the next render) or two-way using @bind-Value, where edits flow back into the bound field immediately upon commit. There is also an uncontrolled mode: give the field a DefaultValue to start from and listen to OnChange, and the component keeps the value itself instead of requiring a backing field - handy for one-off fields inside a form that is read on submit.

The Min and Max parameters bound the value of the field: any value entered or spun outside the range gets clamped to the nearest bound. When they are not provided, the natural range of the underlying numeric type applies (so spinning can never overflow the type). When an explicit bound is provided, the Home and End keys jump the value straight to the minimum and maximum, following the ARIA spinbutton pattern, and the bounds are announced through aria-valuemin/aria-valuemax. Once the value lands on a bound, the button that would step past it stops looking operable and is marked aria-disabled, so the ceiling is visible rather than merely felt - it deliberately keeps its place in the tab order, since in HideInput mode it may well be the element holding the focus. The bounds only apply to what the field itself does with the value: see NoClamp for keeping a typed out-of-range value so a validator can report it, and OnMinReached/OnMaxReached for reacting when a bound is hit.

The Step parameter sets the amount added or removed on each spin, whether it comes from the increment/decrement buttons, the Up/Down arrow keys, or the mouse wheel (while holding Shift). A fractional step such as 0.1 also implies the rounding precision of typed values, unless an explicit Precision is provided. The PageUp and PageDown keys jump by a larger amount: the PageStep parameter when provided, or 10 times the Step otherwise. Combined with Min and Max, stepping stops exactly at the bounds. Stepping always applies to the value currently visible in the input, so typing a number and immediately pressing an arrow key steps from the newly typed value. Holding an increment/decrement button down spins the value continuously; the ContinuousSpinDelay and ContinuousSpinInterval parameters control how soon the continuous spin starts and how fast it runs.

The Precision parameter specifies how many decimal places the value is rounded to whenever it changes. By default no rounding happens (or, if a fractional Step is set, its number of decimals is used). A negative precision rounds to a power of ten, e.g. -2 rounds to the nearest hundred.

Enabling HideInput hides the text input element while keeping the increment/decrement buttons functional, turning the component into a pure stepper control - a quantity picker, for instance. The current value can be surfaced elsewhere, like the label below. Since there is no focusable input left, the buttons take over as the keyboard entry point: they join the tab order and respond to Enter and Space, so the control stays fully operable without a mouse. A hidden input is invisible to assistive technologies as well as to the eye, so the value is additionally published through a visually hidden polite live region - a screen reader user pressing the buttons hears what the value became, exactly as they would from the spinbutton input. The hidden input still carries the value, so the field keeps posting with a plain HTML form. Pair it with a Mode, otherwise nothing is left to interact with.

The value can be changed by scrolling the mouse wheel over the field, under two deliberate conditions that keep the interaction from ever firing by accident: the Shift key must be held down (so plain page scrolling is never captured), and the field must be focused (so merely scrolling past a hovered field never silently rewrites data). By default, scrolling up increments the value; enabling InvertMouseWheel reverses that direction, and NoMouseWheel turns the wheel interaction off altogether while the buttons and the keyboard keep working. The wheel is a spin like any other: it steps by the Step, stops at the Min/Max, and reports through OnIncrement/OnDecrement, so a consumer never has to special-case the input device the change came from.

By default the value is committed when the input loses focus (or on Enter). Enabling Immediate commits on every keystroke (the oninput event) instead. The DebounceTime parameter delays the commit until typing pauses for the given milliseconds, while ThrottleTime rate-limits commits to at most one per interval. While typing in Immediate mode the text you typed stays exactly as typed for as long as it still represents the committed value, so an in-progress number like 1. or 1.50 survives long enough to be finished; the canonical value takes over again as soon as the field loses focus, or immediately if clamping or rounding had to correct what was typed. Combining Immediate with a NumberFormat is best avoided for fractional values: every keystroke is a commit, and each commit re-renders the number from the value, which drops a trailing decimal point before it can be completed.

The ReadOnly parameter makes the whole field read-only: typing, the spin buttons, the arrow keys and the mouse wheel all stop changing the value, but the field remains focusable and its value stays selectable and copyable. The spin buttons are disabled and the clear button is not rendered at all, so nothing in the field looks operable while it is not. The IsInputReadOnly parameter only blocks typing in the input itself, while the value can still be changed using the spin buttons, the arrow keys and the mouse wheel, making the field behave like a stepper with a protected text box - useful when the value must land on the exact grid the stepping produces.

The BitNumberField exposes rich events: OnIncrement and OnDecrement fire when the value is spun (buttons, arrow keys, PageUp/PageDown or the mouse wheel) and receive the new value, OnChange fires whenever the committed value changes, and OnClear fires when the value is cleared using the clear button. OnMinReached and OnMaxReached report the moment a step lands the value on an explicit Min or Max - once per approach, not on every further attempt to pass it - which is the hook for explaining why the value stopped moving instead of leaving the user to guess. The raw input events are surfaced as well: OnKeyDown and OnKeyUp report every key, including the ones the field consumes itself as value commands, OnEnter singles out the Enter key and is raised after the typed text has been committed (so the bound value it sees is the one just entered, which is what makes it usable as a "submit this row" gesture), and OnClick reports clicks on the input. Focus is covered by OnFocus, OnFocusIn, OnFocusOut and OnBlur.

Captured with @ref, the component exposes the same operations its own controls perform, so an external control - a slider, a keypad, a barcode scanner, a hardware button - can drive the field without reimplementing its arithmetic. IncrementAsync and DecrementAsync step by the Step with the bounds, the snapping, the rounding and the OnIncrement/OnDecrement callbacks all applied, and do nothing once the value sits on the bound they would move towards. ClearAsync wipes whatever the field is showing and raises OnClear, without requiring the clear button to be enabled. All three respect the disabled and read-only states, and all three are safe to call from a background thread. FocusAsync (inherited from the input base) moves the caret into the field, and InputElement exposes the underlying element reference for anything else.

Enables culture-agnostic normalization of non-Latin decimal digits (e.g. Persian "۱۲۳" or Arabic "١٢٣") and the Arabic decimal separator (٫) to their Latin equivalents before parsing. This makes the field accept numbers typed from the various Persian/Arabic keyboard layouts that emit different Unicode code points. The same normalization also applies to the Min, Max and Step parameters, so constraints like Min="۱۰" work consistently. The typed digits stay visible in the field as long as they represent the exact bound value.

For full control, provide a custom DigitsNormalizer function. It receives the raw input string and returns the normalized string before parsing, taking precedence over NormalizeDigits. The example below normalizes non-Latin digits and also strips spaces and thousand separators (both Latin "," and Persian "٬").

The BitNumberField integrates with Blazor's EditForm and data annotations out of the box: validation messages show up for out-of-range or missing values, the field gets the invalid styling, and the aria-invalid attribute is rendered automatically for assistive technologies. Text that is not a number at all is reported through the same channel instead of being silently dropped: the rejected text stays in the input so the user can fix it, and the message is taken from ParsingErrorMessage, whose {0} placeholder is filled with the DisplayName (or the bound field name). Setting NoValidate detaches the field from the EditContext entirely, which is what you want for a field that is a UI control rather than part of the edited model.

The TValue type parameter of the BitNumberField accepts every .NET numeric type: byte, sbyte, short, ushort, int, uint, long, ulong, float, double and decimal, plus their nullable variants. Spinning safely clamps at the bounds of the underlying type, so a byte can never overflow past 255 and an int never wraps around at its maximum, and the arithmetic is carried out in a type wide enough that no intermediate step can overflow either - a ulong keeps working past long.MaxValue and a decimal keeps its full precision. The type also picks the mobile keyboard: the fractional types (float, double, decimal) get the decimal keypad and the integral ones the numeric keypad. Neither keypad offers a minus sign on every platform, so a field that must accept negative values on touch devices should ask for the full keyboard with InputMode="BitInputMode.Text".

Enabling SnapToStep snaps every committed value to the nearest multiple of the Step, so typed values land on the same grid that the increment/decrement stepping produces. The grid is anchored at the Min when one is provided (with Min=2 and Step=3 the reachable values are 2, 5, 8, ...), otherwise at zero. It also works with fractional steps, snapping typed decimals to the nearest fraction (e.g. 0.3 becomes 0.25 with a 0.25 step). Without SnapToStep, typed values are kept as-is, aside from min/max clamping and precision rounding. Bear in mind that a Max which is not itself on the grid is unreachable - with Step=3 and Max=10 the highest reachable value is 9 - so the field simply stops there, and a held button ends its press rather than spinning on a value that no longer moves.

By default a typed value outside of the Min/Max range is silently corrected to the nearest bound. That is the right behavior for a stepper, but it hides the mistake when the range is a business rule the user should be told about. Enabling NoClamp lets the out-of-range number through so that the model receives it and a validator (e.g. a [Range] data annotation) can report it, exactly as a plain text input would. The bounds keep their other roles: stepping with the buttons, the arrow keys and the wheel still stops at them, the Home/End keys still jump to them, and they are still announced through aria-valuemin/aria-valuemax.

The input is exposed as an ARIA spinbutton and keeps its aria-valuenow, aria-valuemin, aria-valuemax and aria-valuetext attributes in sync with the value and the configured bounds, so screen readers announce the number, the range and (when the visible text differs from the raw number, e.g. with a NumberFormat or non-Latin digits) how it is read out. aria-valuemin/aria-valuemax only appear for an explicit Min/Max, since announcing the underlying type's extremes would be noise rather than information, and aria-valuenow is left off entirely while the field is empty, which is how ARIA expresses "no value yet". AriaValueText overrides the reading with a human phrase, AriaValueNow overrides the announced number (only meaningful for a controlled field), AriaDescription adds a longer explanation through a visually hidden element, and the visible Description is referenced the same way - both through aria-describedby. The increment, decrement and clear buttons are icon-only, so they always carry an accessible name; it defaults to a sensible English phrase and can be localized using IncrementAriaLabel, DecrementAriaLabel and ClearButtonAriaLabel. Once the value reaches a bound, the button that would step past it is marked aria-disabled rather than being given the disabled attribute, so it is announced as unavailable without vanishing from the accessibility tree or dropping the focus it may be holding. Those buttons stay out of the tab order, keeping the input the single tab stop that handles the whole spinbutton keyboard set - except in HideInput mode, where they become the only control left and therefore turn into keyboard-reachable, Enter/Space-operable buttons, with the value published through a visually hidden live region since the hidden input cannot announce it. AriaSetSize and AriaPositionInSet place the field within a larger group of related fields. Validation failures render aria-invalid automatically, and the focus indicator follows the Accent color (turning to the error color while the field is invalid) so it stays visible against any surface.

The Background parameter picks the fill of the field from the theme's background color kinds (Primary by default), so it can be tuned to the surface it sits on instead of being hard-coded. Transparent is the one to reach for when the field has to disappear into a colored panel, a toolbar or a table cell - pair it with NoBorder or Underlined for a fully seamless look.

The Border parameter picks the color of the field's border from the theme's border color kinds (Primary by default). Transparent keeps the border's one-pixel gutter - so the field neither shifts nor resizes - while making it invisible, which is the difference between it and NoBorder.

The Accent parameter sets the general color of the field: it drives the focus indicator and the tint the icon, the prefix and the suffix take on while the field is focused (Primary by default). It is what lets a number field carry the meaning of what it is editing - a Success accent on a healthy figure, a Warning or Error accent on one that needs attention - without overriding any style by hand. Note that a genuine validation failure still paints the field with the error color regardless of the accent, so the two never contradict each other. Click into the fields below to see each accent.

Use icons from external libraries like FontAwesome, Material Icons, and Bootstrap Icons with the Icon, IncrementIcon, and DecrementIcon parameters.

The appearance can be customized at every level: the root Style and Class parameters, plus the Styles and Classes parameters that target each internal part of the component (root, label, description, input container, input, buttons, icons, prefix, suffix, etc.), including the focus state through the Focused member - which is also the natural place to declare a CSS variable the other parts can then read, as the Styles example below does. Reach for these only where Accent, Background, Border, Underlined and NoBorder cannot express what you need: those keep the field in step with the theme, while a hand-written style does not.

The BitNumberField fully supports right-to-left (RTL) rendering, either using its Dir parameter or a cascading BitDir.Rtl value: the label, the buttons, the required indicator and the input alignment all flip accordingly.