# NumberField Guides ## Patterns ### Quantity Stepper When to use: - a compact row needs exact quantity control Composition notes: - keep decrement and increment on opposite sides of the input - set realistic `min` and `max` Trade-offs: - precise and compact - denser than a simple text input ```tsx import { NumberField, NumberFieldDecrementButton, NumberFieldIncrementButton, NumberFieldInput, Text, } from '@vega-ui/react'; import { useState } from 'react'; interface LineItem { sku: string; name: string; price: number; quantity: number; } const currency = new Intl.NumberFormat('en-US', { style: 'currency', currency: 'USD' }); export default function CartLineItems() { const [items, setItems] = useState([ { sku: 'KB-01', name: 'Mechanical keyboard', price: 129, quantity: 1 }, { sku: 'MS-02', name: 'Wireless mouse', price: 49, quantity: 2 }, { sku: 'HB-07', name: 'USB-C hub, 7 ports', price: 64.9, quantity: 1 }, ]); const changeQuantity = (sku: string, quantity: number) => { setItems((current) => current.map((item) => (item.sku === sku ? { ...item, quantity } : item))); }; const total = items.reduce((sum, item) => { if (Number.isNaN(item.quantity)) return sum; return sum + item.price * item.quantity; }, 0); return (

{items.map((item) => (

{item.name} {currency.format(item.price)}

changeQuantity(item.sku, quantity)}>

))}

Subtotal {currency.format(total)}

); } ``` ### Decimal Adjustment When to use: - pricing, percentages, or measurements require small increments Composition notes: - set `step` and `maximumFractionDigits` intentionally - test rounding behavior with real values Trade-offs: - precise - more fragile than integer-only flows ```tsx import { Label, NumberField, NumberFieldDecrementButton, NumberFieldIncrementButton, NumberFieldInput, Text, } from '@vega-ui/react'; import { useId, useState } from 'react'; const LIST_PRICE = 1290; export const locales = ['en-US', 'ru-RU', 'ar-EG', 'he-IL']; export default function DiscountPercentage({ locale = 'en-US' }: { locale?: string }) { const currency = new Intl.NumberFormat(locale, { style: 'currency', currency: 'USD' }); const id = useId(); const [discount, setDiscount] = useState(12.5); const price = Number.isNaN(discount) ? LIST_PRICE : LIST_PRICE * (1 - discount / 100); return (

Discount % Annual plan: {currency.format(price)} instead of {currency.format(LIST_PRICE)}

); } ``` ### Form-Friendly Numeric Row When to use: - a native form should submit the value directly Composition notes: - put `name` on `NumberFieldInput` - choose default or controlled value model explicitly Trade-offs: - easy native submission - still needs backend validation ```tsx import { Button, Label, NumberField, NumberFieldDecrementButton, NumberFieldIncrementButton, NumberFieldInput, Text, } from '@vega-ui/react'; import { FormEvent, useId, useState } from 'react'; export default function FormSubmitAndReset() { const id = useId(); const [submitted, setSubmitted] = useState(''); const onSubmit = (event: FormEvent) => { event.preventDefault(); const raw = String(new FormData(event.currentTarget).get('monthlyBudget')); const budget = Number(raw.replace(/\s/g, '')); setSubmitted(`Field text “${raw}” → number ${budget}`); }; return ( ); } ``` ## Comparison ### Quick Decision Rule Use `NumberField` when bounds, stepping, or numeric-only interaction matter. Use `TextField` when the value is free-form text, even if it contains digits. ### `NumberField` vs `TextField` Use `NumberField` when: - the value is a real quantity, count, price input, or bounded numeric amount Use `TextField` when: - the value is an identifier, phone number, code, or other digit-containing text ### `NumberField` vs `Slider` Use `NumberField` when: - exact numeric entry matters Use `Slider` when: - fast approximate adjustment matters more than exact typing ### Choose This Component When - users may type or step exact numbers - min, max, and step matter - the same value should be editable by typing and controls without drifting semantics ### Do Not Choose This Component When - the value is not truly numeric - the interaction should be approximate and gesture-first ## Troubleshooting ### The Value Jumps Unexpectedly While Typing #### Symptom Users type a number, but the intermediate value feels unstable. #### Likely Cause The input is being treated as a fully parsed number during intermediate text-editing states. #### How To Verify - type partial values such as `-`, `1.`, or an empty string - inspect how parent state reacts #### Fix Allow intermediate string states in the input flow and parse only when appropriate. ### Step Buttons And Typed Value Drift Apart #### Symptom The field can be typed and stepped, but both interaction modes do not stay in sync. #### Likely Cause Custom parent logic bypasses the root’s own step/bounds model. #### How To Verify - compare typed changes and button clicks on the same field #### Fix Use one source of truth and let the root stepping behavior remain authoritative. ### Mouse Wheel Changes The Value Unexpectedly #### Symptom Scrolling over the control changes the number when users only wanted to scroll the page. #### Likely Cause `changeOnWheel` is enabled in a context where wheel changes are surprising. #### How To Verify - focus the field and scroll over it #### Fix Disable `changeOnWheel` for that integration or move the control away from heavy scrolling regions.