> ## 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. # Campo numerico > Componi un campo numerico con formattazione locale, incrementi, moduli nativi e regolazione tramite trascinamento. ## Panoramica `NumberField` espone tutte e sette le parti del campo numerico Base UI installato: `Root`, `Group`, `Input`, `Decrement`, `Increment`, `ScrubArea` e `ScrubAreaCursor`. Importalo da `twenty-ui/primitives/input`. Mantiene lo stato numerico, la formattazione, gli incrementi, i dettagli degli eventi e l'integrazione con i moduli nativi di Base UI, con lo stile di Twenty UI per i controlli di input, gruppo e regolazione. Per il preset compatto con formattazione fissa e valori predefiniti dei passaggi modificatori, usa [NumberStepper](https://docs.twenty.com/it/ui/components/input/number-stepper.md) da `twenty-ui/components/input`. **Light** [Esempio di NumberField (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--display\&viewMode=story\&globals=colorScheme:light) **Dark** [Esempio di 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) ## Utilizzo `Root` gestisce lo stato numerico. `Input` è l'input di testo visibile. Usa `Group` per disporre attorno a esso i controlli facoltativi di decremento e incremento. Fornisci contenuto e nomi accessibili per i controlli; il componente primitivo non inserisce icone né etichette. ```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` e `Field.Error` si associano all'input visibile. In alternativa, passa `aria-label` o `aria-labelledby` a `Input`. Il valore predefinito di `aria-roledescription` è `Number field`; non fornisce un nome accessibile. ## Valori e callback Ometti `value` per un campo non controllato e fornisci un `defaultValue` numerico quando è necessario un valore iniziale. Omettendo `defaultValue`, il campo inizia vuoto. Per un campo controllato, passa un numero o `null` tramite `value` e aggiornalo da `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'} ); }; ``` La cancellazione restituisce `null`, incluso quando è impostato `min`. Bozze incomplete come `-` rimangono modificabili senza segnalare un numero non valido. La digitazione analizzabile aggiorna il valore numerico prima che la modifica venga confermata. Il primo passaggio da un valore vuoto inizia da zero, vincolato ai limiti; i passaggi successivi usano l'incremento attivo. `onValueChange(value, details)` mantiene `event`, `reason`, `cancel`, `allowPropagation`, `isCanceled`, `isPropagationAllowed`, `trigger` nativi e `direction` facoltativo. I motivi distinguono la digitazione (`input-change`), la cancellazione (`input-clear`), la normalizzazione alla perdita del focus (`input-blur`), l'incollamento (`input-paste`), tastiera, pressioni di incremento o decremento, rotellina, scrubbing e riempimento automatico nativo (`none`). La chiamata a `cancel()` impedisce l'aggiornamento dello stato numerico; i chiamanti controllati scelgono comunque il valore accettato. `onValueCommitted(value, details)` viene eseguito alla perdita del focus dopo la modifica, al rilascio del puntatore dopo il passaggio o lo scrubbing e immediatamente per le regolazioni tramite tastiera e rotellina. La cancellazione conferma `null` alla perdita del focus. I dettagli del commit contengono `event` e `reason`; sono dettagli generici senza metodi di annullamento delle modifiche. Mettere e togliere il focus a un campo non modificato non conferma di per sé un valore quando non è necessaria alcuna normalizzazione numerica. Le opzioni esplicite di arrotondamento possono normalizzare e confermare un valore non modificato. ## Lingua e formattazione Imposta `locale` e `format` su `Root`. Mantengono il contratto Base UI installato: `locale` accetta `Intl.LocalesArgument` e `format` accetta `Intl.NumberFormatOptions`. La formattazione visualizzata è separata dal valore numerico non elaborato inviato dal modulo. Il componente primitivo non impone cifre latine, raggruppamento, precisione o passaggi modificatori. **Light** [Formattazione della lingua e della valuta (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--locale-currency\&viewMode=story\&globals=colorScheme:light) **Dark** [Formattazione della lingua e della valuta (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 ); ``` La digitazione e l'incollamento usano la lingua configurata e i simboli di formato supportati. La perdita del focus normalizza il testo visualizzato. Le opzioni esplicite di precisione o arrotondamento possono inoltre normalizzare il numero confermato; senza tali opzioni, la sola formattazione non sostituisce un valore numerico non modificato con testo visualizzato arrotondato. ## Passaggi e limiti `step` è predefinito a `1`, `smallStep` a `0.1` mentre si tiene premuto Alt e `largeStep` a `10` mentre si tiene premuto Shift. Il passaggio attivo si applica a pulsanti, Freccia su e Freccia giù, rotellina e movimento nell'area di scrubbing. `snapOnStep` è predefinito a `false`; abilitalo per allineare le regolazioni al passaggio attivo. Home ed End selezionano il limite esplicito corrispondente. I gestori di tasti nativi possono chiamare `event.preventBaseUIHandler()` quando il proprietario deve sovrascrivere il comportamento della tastiera di Base UI. `min` e `max` sono inclusivi. Le interazioni di passaggio rimangono entro i limiti. Per impostazione predefinita, anche i valori digitati e incollati vengono limitati numericamente, con la bozza normalizzata alla perdita del focus. Imposta `allowOutOfRange` per accettare modifiche dirette al di fuori di tali limiti e lasciare che la convalida nativa dell'intervallo o dell'applicazione segnali il problema. `step="any"` disabilita la convalida nativa del passaggio, mentre il passaggio interattivo usa `1` e i passaggi modificatori configurati. Con un passaggio numerico, fornisci esplicitamente `min` quando l'invio nativo deve convalidare l'allineamento al passaggio. Il passaggio numerico non arrotonda ogni valore digitato a un passaggio. ## Scorrimento `ScrubArea` modifica il valore numerico mentre il puntatore si muove. Supporta il movimento orizzontale o verticale, `pixelSensitivity` e `teleportDistance` facoltativo. Il passaggio attivo e i limiti si applicano anche allo scrubbing. Usa un'etichetta visibile come destinazione dello scrubbing mantenendo disponibile l'input per la modifica tramite tastiera. **Light** [Esegui lo scrubbing dell'etichetta della larghezza (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberfield--with-scrubbing\&viewMode=story\&globals=colorScheme:light) **Dark** [Esegui lo scrubbing dell'etichetta della larghezza (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) Componi `ScrubAreaCursor` all'interno di `ScrubArea` per un cursore personalizzato durante lo scrubbing con blocco del puntatore. Quando è attivo, viene inserito tramite portale nel corpo del documento. Base UI usa il cursore normale come fallback per l'input touch, il blocco del puntatore negato e WebKit. Imposta `allowWheelScrub` su `Root` per consentire la regolazione tramite rotellina mentre l'input ha il focus e il puntatore è sopra di esso; il valore predefinito è `false`. ## Moduli e stato disabilitato `Root` esegue il rendering di un `input type="number"` nativo nascosto per l'invio numerico non elaborato e la convalida nativa. Imposta `name`, `form`, `required`, `min`, `max` e `step` su `Root`. `form` può associare il campo a un modulo in un'altra posizione del documento. I controlli di regolazione predefiniti usano `type="button"`, quindi il passaggio non invia il modulo. `disabled` impedisce l'interazione ed esclude il valore dall'invio. `readOnly` impedisce le modifiche mantenendo l'input visibile selezionabile tramite focus e rendendo disponibile il suo valore del modulo. Usa un valore controllato quando l'applicazione deve reimpostare lo stato numerico; il reimpostazione del modulo nativo non lo reimposta. ## Destinazioni DOM e personalizzazione | Parte o prop | Destinazione DOM e ref predefinita | | - | - | | `Root` / `Root.ref` | Il `div` esterno | | `Root.inputRef` | L'input numerico nativo nascosto | | `Root.id` | Associa l'ID dell'input di testo visibile | | `Group` / `Group.ref` | Il `div` del gruppo | | `Input` / `Input.ref` | L'`input type="text"` visibile | | `Decrement` / `Increment` | Pulsanti nativi | | `ScrubArea` | Uno `span` | | `ScrubAreaCursor` | Uno `span` inserito tramite portale nel corpo del documento quando è attivo; altrimenti il relativo ref è null | Gli attributi nativi, `className`, `style` e `render` hanno come destinazione la parte che li riceve. La personalizzazione dell'input si applica al controllo visibile; la personalizzazione del wrapper va applicata a `Root` o `Group`. Per mettere a fuoco il controllo, usa `Input.ref` anziché `Root.inputRef`. Ogni parte accetta un elemento o un callback tramite `render`, con il tipo di stato pubblico corrispondente. Inoltra le props e il ref forniti all'elemento DOM appropriato affinché modifica, focus, etichette e convalida continuino a funzionare. Quando un controllo di passaggio esegue il rendering di un elemento che non è un pulsante, imposta `nativeButton={false}`. Anche `className` e `style` accettano callback di stato. Lo stato include `value` numerico, `inputValue` formattato, `required`, `disabled`, `readOnly`, `scrubbing` e lo stato Field ereditato. I punti di ingresso pubblici esportano le props e il tipo di stato per ogni parte, oltre a `NumberFieldRootChangeEventDetails`, `NumberFieldRootChangeEventReason`, `NumberFieldRootCommitEventDetails` e `NumberFieldRootCommitEventReason`. ## Renderer del componente front-end Le fixture sandbox di React e Preact verificano la formattazione iniziale della lingua, l'incollamento localizzato, i valori numerici non elaborati del modulo, le etichette accessibili, i ref, la composizione del rendering, i commit alla perdita del focus, i dettagli di modifica e commit tramite tastiera e i dettagli di modifica tramite puntatore. La digitazione sequenziale dopo aver cancellato un campo localizzato controllato attualmente reimposta il cursore nel renderer: digitare `2` e poi `3` può produrre `32`. Una regolazione formattata tramite puntatore può anche entrare in conflitto con la perdita del focus e lasciare l'input visibile con il valore precedente. Le regolazioni tramite puntatore segnalano le modifiche, ma il rilascio del puntatore non invia il callback di commit corrispondente; la successiva perdita del focus può invece confermare con `input-blur`. Anche il trascinamento dell'area di scrubbing e l'uso del relativo cursore personalizzato non sono disponibili nella sandbox. Queste limitazioni non influiscono sugli host React ordinari. ## Props Il riferimento è generato dai tipi pubblici del componente installato. Gli attributi nativi e i gestori di eventi sono accettati anche sulle parti che eseguono il rendering di elementi. ### 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.