WinUI NumberBox Formatting and Validation

NumberBox is a numeric entry control that supports validation, increment stepping, and even inline calculations. The examples below demonstrate how to format floating-point values, enforce safe ranges, and keep keyboard/touch experiences predictable.

Overview

• Supports integer and floating-point entry, expression parsing, and increment/decrement behaviors.
• Provides Minimum, Maximum, and SmallChange/LargeChange properties for clamping values.
• Emits ValueChanged events, making it easy to validate or react to changes in view models.

Prerequisites

• WinUI 3 project referencing Microsoft.UI.Xaml.Controls.NumberBox
• INumberFormatter2 implementation for custom numeric formatting
• Localization plan for decimal separators if your app targets multiple locales

Format floating-point values

Floating-point rounding errors (for example 2.46 displaying as 2.45999999) are common when the default formatter is used. Implement INumberFormatter2 and INumberParser to normalize incoming values and produce consistent string output.

<Page.Resources>
    <helpers:DoubleFormatter x:Key="DoubleFormatter" Format="{0:F2}" />
</Page.Resources>

...

<NumberBox Value="{x:Bind Value, Mode=TwoWay}"
           NumberFormatter="{StaticResource DoubleFormatter}"
           SmallChange="0.1"
           LargeChange="1"
           SpinButtonPlacementMode="Inline" />

public sealed class DoubleFormatter : INumberFormatter2, INumberParser
{
    public string Format { get; set; } = "{0:F2}";

    public string FormatDouble(double value)
    {
        return string.Format(Format, Math.Round(value, 2));
    }

    public string FormatInt(long value)
        => throw new NotSupportedException();

    public string FormatUInt(ulong value)
        => throw new NotSupportedException();

    public double? ParseDouble(string text)
    {
        return double.TryParse(text, out var result)
            ? Math.Round(result, 2)
            : null;
    }

    public long? ParseInt(string text)
        => throw new NotSupportedException();

    public ulong? ParseUInt(string text)
        => throw new NotSupportedException();
}

Keep the formatter culture-aware by using CultureInfo.CurrentCulture when parsing or formatting values if your users rely on localized decimal separators.

Validation strategies

• Clamping: Use Minimum and Maximum properties to keep values inside safe bounds. Combine with SpinButtonPlacementMode for faster adjustments.
• Expression handling: When AcceptsExpression="True", handle the ValueChanged event to detect invalid expressions and provide clear error messages.
• Data binding: Bind Value with Mode=TwoWay and rely on INotifyDataErrorInfo or DataAnnotations in your view model for consistent validation messaging.

Accessibility and input tips

• Provide Header text that describes the unit (for example, “Weight (kg)”) so screen readers announce context.
• Keep SmallChange conservative (for example 0.1) and assign LargeChange for keyboard Page Up/Down actions.
• When capturing sensitive data (like currency), set PreventKeyboardDisplayOnProgrammaticFocus="True" if you manage focus manually to avoid popping an on-screen keyboard unexpectedly.