syncfusion-maui-toolkit-numeric-updown

name	syncfusion-maui-toolkit-numeric-updown
description	Implement the Syncfusion .NET MAUI NumericUpDown control for numeric input with validation, formatting, and increment/decrement buttons. Use this skill when building forms requiring numeric entry with up-down buttons, currency formatting, percentage values, decimal precision, custom formats, input validation, or placeholder text.
metadata	{"author":"Syncfusion Inc","version":"1.0.0"}

Syncfusion .NET MAUI NumericUpDown

The SfNumericUpDown control provides a user-friendly numeric input experience with built-in validation, formatting options, and convenient increment/decrement buttons. Perfect for building professional forms that require validated numeric entry.

When to Use This Skill

Use this skill when you need to:

• Build numeric input fields in .NET MAUI applications
• Format numbers as currency (C2), percentages (P2), or decimals (N2)
• Restrict input to valid ranges (Minimum/Maximum values)
• Provide quick value adjustments with up/down arrow buttons or keyboard controls
• Display placeholders for empty numeric fields
• Handle validation automatically with OnKeyFocus or OnLostFocus modes
• Customize appearance of buttons, colors, borders, and fonts
• Support cultural formats with culture-aware number display

Component Overview

The SfNumericUpDown (or NumericUpDown) control is a specialized input field designed for entering and editing numeric values in .NET MAUI applications. It combines three interaction patterns:

What It Does:

• Accepts numeric input with optional text field for direct entry
• Provides increment/decrement buttons (up/down arrows) for quick value adjustment
• Supports keyboard navigation (arrow keys, Page Up/Down, Tab, Return)
• Enforces validation with configurable ranges (Minimum/Maximum)
• Formats numbers according to culture, currency, or custom specifications
• Displays placeholder text when no value is set

Key Characteristics:

• Smart Validation: OnKeyFocus (real-time) or OnLostFocus (deferred) validation modes
• Flexible Formatting: Currency (C2), percentages (P2), decimals (N2), or custom formats
• Customizable Buttons: Placement modes (Inline, InlineVertical), alignment (Left, Right, Both), color, and custom templates
• Constraint Support: Min/Max ranges, null handling (AllowNull), text-only mode (IsEditable=false)
• Event Driven: ValueChanged, Completed, Focused/Unfocused events for form integration
• Accessible: Support for WCAG compliance, screen readers, and keyboard-only navigation

When to Choose NumericUpDown:

• Need a professional numeric input with built-in increment buttons
• Want automatic validation and formatting without custom code
• Building financial forms (prices, discounts, percentages)
• Creating inventory systems (quantities, stock levels)
• Implementing settings or preference screens
• Need culture-aware number formatting

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and NuGet package setup
• Registering handlers in MauiProgram.cs
• Adding a basic NumericUpDown control
• XAML and C# initialization patterns
• First render and validation modes

Value Management & Constraints

📄 Read: references/value-management.md

• Setting and binding numeric values
• Minimum and Maximum value restrictions
• Null value handling with AllowNull property
• Default values and initial setup
• Preventing manual text editing with IsEditable

Formatting & Display Options

📄 Read: references/formatting-display.md

• Custom number formats (currency, percentage, decimal)
• Placeholder text and placeholder color customization
• Culture-aware number display
• Maximum decimal digits management
• Percentage display modes (Value vs Compute)
• Custom format specifiers (0, #, C, P, N)

Validation & Events

📄 Read: references/validation-events.md

• ValueChanged event with OldValue and NewValue
• Completed event when editing is finished
• Focused and Unfocused events
• ValueChangeMode (OnKeyFocus vs OnLostFocus)
• Programmatic focus management
• Return key commands

Up/Down Button Control

📄 Read: references/buttons-updown.md

• SmallChange and LargeChange increments
• Keyboard shortcuts (Arrow keys, Page Up/Down)
• Mouse scroll wheel support
• Up/Down button placement modes (Inline, InlineVertical)
• Button alignment (Left, Right, Both)
• Button color customization
• Custom button templates
• Auto-reverse behavior

Customization & UI Features

📄 Read: references/customization.md

• Border visibility and stroke color
• Text color and alignment customization
• Font family, size, and attributes
• Clear button visibility and customization
• Cursor position and text selection
• Return key types and keyboard behavior
• Advanced styling patterns
• Common gotchas and troubleshooting