> ## Documentation Index > Fetch the complete documentation index at: https://docs.twenty.com/llms.txt > Use this file to discover all available pages before exploring further. # Câmp numeric > Compuneți un câmp numeric cu formatare locală, incrementare, formulare native și ajustare prin glisare. ## Prezentare generală `NumberField` expune toate cele șapte componente ale câmpului numeric Base UI instalat: `Root`, `Group`, `Input`, `Decrement`, `Increment`, `ScrubArea` și `ScrubAreaCursor`. Importați-l din `twenty-ui/primitives/input`. Păstrează starea numerică, formatarea, incrementarea, detaliile evenimentelor și integrarea formularelor native din Base UI, cu stilizarea Twenty UI pentru comenzile de introducere, grupare și ajustare. Pentru presetarea compactă cu formatare fixă și valori implicite pentru pașii modificatori, utilizați [NumberStepper](https://docs.twenty.com/ro/ui/components/input/number-stepper.md) din `twenty-ui/components/input`. **Light** [Exemplu NumberField (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--display\&viewMode=story\&globals=colorScheme:light) **Dark** [Exemplu NumberField (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--display\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--display) ## Utilizare `Root` gestionează starea numerică. `Input` este introducerea de text vizibilă. Utilizați `Group` pentru a aranja în jurul acestuia controalele opționale de decrementare și incrementare. Furnizați conținut și nume accesibile pentru controale; primitiva nu inserează pictograme sau etichete. ```tsx theme={null} import { IconMinus, IconPlus } from 'twenty-ui/icon'; import { Field, NumberField } from 'twenty-ui/primitives/input'; export const QuantityInput = () => ( Quantity Choose up to ten items. ); ``` `Field.Label`, `Field.Description` și `Field.Error` se asociază cu introducerea vizibilă. Alternativ, transmiteți `aria-label` sau `aria-labelledby` către `Input`. Valoarea implicită pentru `aria-roledescription` este `Number field`; aceasta nu oferă un nume accesibil. ## Valori și callbackuri Omiteți `value` pentru un câmp necontrolat și furnizați un `defaultValue` numeric atunci când este necesară o valoare inițială. Omiterea lui `defaultValue` pornește cu un câmp gol. Pentru un câmp controlat, transmiteți un număr sau `null` prin `value` și actualizați-l din `onValueChange`. ```tsx theme={null} import { useState } from 'react'; import { Field, NumberField } from 'twenty-ui/primitives/input'; export const PriceInput = () => { const [price, setPrice] = useState(null); const [savedPrice, setSavedPrice] = useState(null); return ( Price Last committed price: {savedPrice ?? 'empty'} ); }; ``` Golirea raportează `null`, inclusiv când este setat `min`. Schițele incomplete, precum `-`, rămân editabile fără a raporta un număr nevalid. Tastarea care poate fi analizată actualizează valoarea numerică înainte ca editarea să fie confirmată. Primul pas de la o valoare goală pornește de la zero, limitat la granițe; pașii următori folosesc valoarea pasului activ. `onValueChange(value, details)` păstrează `event`, `reason`, `cancel`, `allowPropagation`, `isCanceled`, `isPropagationAllowed`, `trigger` și `direction` opțional. Motivele disting tastarea (`input-change`), golirea (`input-clear`), normalizarea la pierderea focalizării (`input-blur`), lipirea (`input-paste`), apăsările de taste, incrementarea sau decrementarea, rotița, ajustarea prin glisare și completarea automată nativă (`none`). Apelarea `cancel()` împiedică actualizarea stării numerice; apelanții controlați aleg în continuare valoarea acceptată. `onValueCommitted(value, details)` se execută la pierderea focalizării după editare, la eliberarea indicatorului după incrementare/decrementare sau ajustare prin glisare și imediat pentru ajustările prin tastatură și rotiță. Golirea confirmă `null` la pierderea focalizării. Detaliile confirmării conțin `event` și `reason`; sunt detalii generice fără metode de anulare a modificării. Focalizarea și pierderea focalizării unui câmp neatins nu confirmă prin ele însele o valoare atunci când nu este necesară nicio normalizare numerică. Opțiunile explicite de rotunjire pot normaliza și confirma o valoare neatinsă. ## Setări regionale și formatare Setați `locale` și `format` pe `Root`. Acestea păstrează contractul Base UI instalat: `locale` acceptă `Intl.LocalesArgument`, iar `format` acceptă `Intl.NumberFormatOptions`. Formatarea afișării este separată de valoarea numerică brută transmisă de formular. Primitiva nu impune cifre latine, grupare, precizie sau pași modificatori. **Light** [Formatarea setărilor regionale și a monedei (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--locale-currency\&viewMode=story\&globals=colorScheme:light) **Dark** [Formatarea setărilor regionale și a monedei (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--locale-currency\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--locale-currency) ```tsx theme={null} import { Field, NumberField } from 'twenty-ui/primitives/input'; export const AmountInput = () => ( Amount in euros ); ``` Tastarea și lipirea folosesc setările regionale configurate și simbolurile de format acceptate. Pierderea focalizării normalizează textul afișat. Opțiunile explicite de precizie sau rotunjire pot normaliza și numărul confirmat; fără aceste opțiuni, formatarea singură nu înlocuiește o valoare numerică neatinsă cu text de afișare rotunjit. ## Pași și limite `step` are implicit valoarea `1`, `smallStep` are valoarea `0.1` cât timp Alt este apăsată, iar `largeStep` are valoarea `10` cât timp Shift este apăsată. Pasul activ se aplică butoanelor, tastelor Săgeată sus și Săgeată jos, rotiței și deplasării în zona de ajustare prin glisare. `snapOnStep` are implicit valoarea `false`; activați-l pentru a alinia ajustările la pasul activ. Home și End selectează limita explicită corespunzătoare. Gestionarii nativi ai tastelor pot apela `event.preventBaseUIHandler()` atunci când proprietarul trebuie să suprascrie comportamentul de tastatură al Base UI. `min` și `max` sunt incluzive. Interacțiunile de incrementare/decrementare rămân în limite. În mod implicit, valorile tastate și lipite sunt și ele limitate numeric, iar schița este normalizată la pierderea focalizării. Setați `allowOutOfRange` pentru a accepta editări directe în afara acelor limite și pentru a permite validării native a intervalului sau validării aplicației să raporteze problema. `step="any"` dezactivează validarea nativă a pașilor, în timp ce incrementarea/decrementarea interactivă utilizează `1` și pașii modificatori configurați. Cu un pas numeric, furnizați explicit `min` atunci când transmiterea nativă trebuie să valideze alinierea la pas. Pasul numeric nu rotunjește fiecare valoare tastată la un pas. ## Ajustare prin glisare `ScrubArea` modifică valoarea numerică pe măsură ce indicatorul se deplasează. Acceptă deplasarea orizontală sau verticală, `pixelSensitivity` și `teleportDistance` opțional. Pasul activ și limitele se aplică și ajustării prin glisare. Utilizați o etichetă vizibilă ca țintă pentru ajustarea prin glisare, păstrând în același timp introducerea disponibilă pentru editare cu tastatura. **Light** [Ajustați prin glisare eticheta lățimii (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--with-scrubbing\&viewMode=story\&globals=colorScheme:light) **Dark** [Ajustați prin glisare eticheta lățimii (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--with-scrubbing\&viewMode=story\&globals=colorScheme:dark) [Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberfield--with-scrubbing) Compuneți `ScrubAreaCursor` în interiorul `ScrubArea` pentru un cursor personalizat în timpul ajustării prin glisare cu blocarea indicatorului. Acesta este portalizat în corpul documentului cât timp este activ. Base UI revine la cursorul normal pentru introducerea tactilă, blocarea indicatorului refuzată și WebKit. Setați `allowWheelScrub` pe `Root` pentru a permite ajustarea cu rotița cât timp introducerea este focalizată și sub indicator; valoarea implicită este `false`. ## Formulare și stare dezactivată `Root` redă un `input type="number"` nativ ascuns pentru transmiterea numerică brută și validarea nativă. Setați `name`, `form`, `required`, `min`, `max` și `step` pe `Root`. `form` poate asocia câmpul cu un formular din altă parte a documentului. Controalele de ajustare implicite utilizează `type="button"`, astfel încât incrementarea/decrementarea nu transmite formularul. `disabled` împiedică interacțiunea și exclude valoarea de la transmitere. `readOnly` împiedică modificările, păstrând în același timp introducerea vizibilă focalizabilă și valoarea sa de formular disponibilă. Utilizați o valoare controlată atunci când aplicația trebuie să reseteze starea numerică; resetarea nativă a formularului nu o resetează. ## Ținte DOM și personalizare | Parte sau proprietate | Țintă DOM și ref implicită | | - | - | | `Root` / `Root.ref` | `div` exterior | | `Root.inputRef` | Introducerea numerică nativă ascunsă | | `Root.id` | Asociază ID-ul introducerii de text vizibile | | `Group` / `Group.ref` | `div` al grupului | | `Input` / `Input.ref` | `input type="text"` vizibil | | `Decrement` / `Increment` | Butoane native | | `ScrubArea` | Un `span` | | `ScrubAreaCursor` | Un `span` portalizat în corpul documentului cât timp este activ; în rest, referința sa este nulă | Atributele native, `className`, `style` și `render` vizează partea care le primește. Personalizarea introducerii se aplică controlului vizibil; personalizarea învelișului aparține lui `Root` sau `Group`. Pentru a focaliza controlul, utilizați `Input.ref`, nu `Root.inputRef`. Fiecare parte acceptă un element sau un callback prin `render`, cu tipul de stare public corespunzător. Transmiteți proprietățile și referința furnizate către elementul DOM corespunzător, astfel încât editarea, focalizarea, etichetele și validarea să continue să funcționeze. Când un control de incrementare/decrementare redă un element care nu este buton, setați `nativeButton={false}`. `className` și `style` acceptă și callbackuri de stare. Starea include `value` numeric, `inputValue` formatat, `required`, `disabled`, `readOnly`, `scrubbing` și starea Field moștenită. Punctele de intrare publice exportă proprietățile și tipul de stare pentru fiecare parte, plus `NumberFieldRootChangeEventDetails`, `NumberFieldRootChangeEventReason`, `NumberFieldRootCommitEventDetails` și `NumberFieldRootCommitEventReason`. ## Rendererul componentei Front Fixture-urile sandbox React și Preact verifică formatarea inițială a setărilor regionale, lipirea localizată, valorile brute numerice ale formularului, etichetele accesibile, referințele, compunerea redării, confirmările la pierderea focalizării, detaliile modificării și confirmării prin tastatură și detaliile modificării prin indicator. Tastarea secvențială după golirea unui câmp localizat controlat resetează în prezent cursorul de inserare în renderer: tastarea lui `2` și apoi a lui `3` poate produce `32`. O ajustare formatată cu indicatorul poate, de asemenea, să intre în concurență cu pierderea focalizării și să lase introducerea vizibilă afișând valoarea anterioară. Ajustările cu indicatorul raportează modificări, dar eliberarea indicatorului nu furnizează callbackul de confirmare corespunzător; pierderea focalizării ulterioară poate confirma în schimb cu `input-blur`. Glisarea zonei de ajustare și utilizarea cursorului său personalizat nu sunt disponibile nici în sandbox. Aceste limitări nu afectează gazdele React obișnuite. ## Proprietăți Referința este generată din tipurile publice ale componentelor instalate. Atributele native și gestionarii de evenimente sunt, de asemenea, acceptați în părțile care redau elemente. ### NumberField.Root **Root.allowOutOfRange** `boolean` (default: false) Allows typed, pasted, and autofilled values outside min and max. Native range validation still applies; step interactions remain bounded. **Root.allowWheelScrub** `boolean` (default: false) Allows wheel adjustments while the visible input is focused and hovered. Defaults to false. **Root.children** `ReactNode` Composed NumberField parts and supporting content. **Root.className** `string | ((state: NumberFieldRootState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Root.defaultValue** `number` (default: empty) Initial uncontrolled number. Omit to start empty; the public type accepts a number. **Root.disabled** `boolean` (default: false) Prevents interaction and excludes the value from form submission. **Root.form** `string` ID of the form owning the hidden native number input. **Root.format** `NumberFormatOptions` Intl.NumberFormat options for display and parsing, including currency, units, percent, grouping, and precision. Explicit rounding options can normalize the committed value on blur. **Root.id** `string` ID associated with the visible input. Generated when omitted. **Root.inputRef** `Ref\` Ref to the hidden native number input used for submission and validation. Use Input.ref to focus the visible text input. **Root.largeStep** `number` (default: 10) Amount used while Shift is held. Defaults to 10. **Root.locale** `LocalesArgument` Locale or locale list used to format and parse numbers. Defaults to the runtime locale. **Root.max** `number` Inclusive maximum for stepping and native range validation. **Root.min** `number` Inclusive minimum for stepping and native range validation. **Root.name** `string` Name of the raw numeric value submitted by the hidden input. **Root.onValueChange** `((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) =\> void)` Receives the next number or null and change details with the native event, reason, cancellation and propagation methods, and optional stepping direction. **Root.onValueCommitted** `((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) =\> void)` Receives the committed number or null and generic details containing event and reason. Typing commits on blur; pointer steps and scrubbing commit on release; keyboard and wheel changes commit immediately. **Root.readOnly** `boolean` (default: false) Prevents changes while keeping the visible input focusable. **Root.ref** `Ref\` Ref to the root div, or the element composed through Root.render. **Root.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Root.required** `boolean` (default: false) Requires a numeric value for native form submission. **Root.smallStep** `number` (default: 0.1) Amount used while Alt is held. Defaults to 0.1. **Root.snapOnStep** `boolean` (default: false) Snaps step interactions to multiples of the active step. Defaults to false. **Root.step** `number | "any"` (default: 1) Base amount for buttons, arrow keys, wheel, and scrubbing. Use any to disable native step validation while stepping by 1. **Root.style** `CSSProperties | ((state: NumberFieldRootState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. **Root.value** `number | null` Controlled raw numeric value. Use null for an empty field. ### NumberField.Group **Group.children** `ReactNode` The visible input and any increment or decrement controls. **Group.className** `string | ((state: NumberFieldGroupState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Group.ref** `Ref\` Ref to the group div, or the element composed through Group.render. **Group.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Group.style** `CSSProperties | ((state: NumberFieldGroupState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Input **Input.aria-roledescription** `string` (default: Number field) Describes the role to assistive technology. Defaults to Number field; use Field.Label, aria-label, or aria-labelledby for the accessible name. **Input.className** `string | ((state: NumberFieldInputState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Input.ref** `Ref\` Ref to the visible native text input. **Input.render** `ReactElement\\> | ComponentRenderFn\, HTMLInputElement\>, NumberFieldInputState\>` Composes the visible text input with an element or render callback. Forward the supplied props and ref to an input. Customize layout through Root or Group. **Input.size** `number` Native input size attribute. Use styles to customize visual dimensions. **Input.style** `CSSProperties | ((state: NumberFieldInputState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Increment **Increment.children** `ReactNode` Visible content for the increment control. Supply its accessible name. **Increment.className** `string | ((state: NumberFieldIncrementState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Increment.nativeButton** `boolean` (default: true) Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction. **Increment.ref** `Ref\` Ref to the increment button, or the element composed through render. **Increment.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Increment.style** `CSSProperties | ((state: NumberFieldIncrementState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.Decrement **Decrement.children** `ReactNode` Visible content for the decrement control. Supply its accessible name. **Decrement.className** `string | ((state: NumberFieldDecrementState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **Decrement.nativeButton** `boolean` (default: true) Whether render composes a native button. Set false for a custom non-button element so Base UI supplies button interaction. **Decrement.ref** `Ref\` Ref to the decrement button, or the element composed through render. **Decrement.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **Decrement.style** `CSSProperties | ((state: NumberFieldDecrementState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. ### NumberField.ScrubArea **ScrubArea.children** `ReactNode` Content the user can drag to adjust the number, plus an optional ScrubAreaCursor. **ScrubArea.className** `string | ((state: NumberFieldScrubAreaState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **ScrubArea.direction** `"horizontal" | "vertical"` (default: horizontal) Pointer movement direction used for scrubbing. **ScrubArea.pixelSensitivity** `number` (default: 2) Pixels of pointer movement needed for a step. Larger values reduce sensitivity. **ScrubArea.ref** `Ref\` Ref to the scrub area span, or the element composed through render. **ScrubArea.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **ScrubArea.style** `CSSProperties | ((state: NumberFieldScrubAreaState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. **ScrubArea.teleportDistance** `number` Optional distance from the scrub area center at which the pointer loops around. ### NumberField.ScrubAreaCursor **ScrubAreaCursor.children** `ReactNode` Custom cursor content shown during supported pointer-lock scrubbing. **ScrubAreaCursor.className** `string | ((state: NumberFieldScrubAreaCursorState) =\> string | undefined)` Class applied to this part, or a callback receiving its NumberField state. **ScrubAreaCursor.ref** `Ref\` Ref to the cursor span portaled to the document body while active. Null while absent. **ScrubAreaCursor.render** `ReactElement\\> | ComponentRenderFn\` Composes this part with an element or render callback. Forward the supplied props and ref to the corresponding DOM element. **ScrubAreaCursor.style** `CSSProperties | ((state: NumberFieldScrubAreaCursorState) =\> CSSProperties | undefined)` Inline styles applied to this part, or a callback receiving its NumberField state. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.