> ## 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.

# NumberStepper

> Modifica un numero con limiti facoltativi e pulsanti di incremento o decremento.

## Panoramica

`NumberStepper` è il preset compatto e pratico basato su [NumberField](https://docs.twenty.com/it/ui/primitives/input/number-field.md). Combina un input di testo numerico con pulsanti facoltativi di decremento e incremento. Importalo da `twenty-ui/components/input`. Usa `NumberField` quando ti servono opzioni relative alle impostazioni locali o alla formattazione, passaggi dei modificatori diversi, lo scrubbing o la composizione indipendente delle parti.

**Light**

[Esempio di NumberStepper (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Esempio di NumberStepper (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberstepper--display)

## Utilizzo

```tsx theme={null}
import { NumberStepper } from 'twenty-ui/components/input';
import { Field } from 'twenty-ui/primitives/input';

export const QuantityInput = () => (
  <Field.Root>
    <Field.Label style={{ color: 'var(--t-font-color-primary)' }}>
      Quantity
    </Field.Label>
    <NumberStepper defaultValue={3} min={0} max={10} />
    <Field.Description style={{ color: 'var(--t-font-color-secondary)' }}>
      Choose up to ten items.
    </Field.Description>
  </Field.Root>
);
```

## Opzioni visive

Confronta gli stati predefinito, limitato, disabilitato, di sola lettura e non valido, con o senza pulsanti di incremento.

**Light**

[Limiti e stati del selettore numerico (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Limiti e stati del selettore numerico (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-numberstepper--catalog)

## Valore non controllato

Usa `defaultValue` per impostare la quantità iniziale. L'input gestisce le modifiche successive.

```tsx theme={null}
import { NumberStepper } from 'twenty-ui/components/input';
import { Field } from 'twenty-ui/primitives/input';

export const QuantityInput = () => (
  <Field.Root>
    <Field.Label>Quantity</Field.Label>
    <NumberStepper name="quantity" defaultValue={3} min={0} max={10} step={1} />
    <Field.Description>Choose up to ten items.</Field.Description>
  </Field.Root>
);
```

## Valore controllato

Passa un numero o `null` tramite `value` e aggiornalo in `onValueChange` per gestire la stessa quantità nello stato React. Il callback riceve il valore numerico successivo e i dettagli dell'evento.

```tsx theme={null}
import { useState } from 'react';
import { NumberStepper } from 'twenty-ui/components/input';
import { Field } from 'twenty-ui/primitives/input';

export const QuantityInput = () => {
  const [quantity, setQuantity] = useState<number | null>(3);

  return (
    <Field.Root>
      <Field.Label>Quantity</Field.Label>
      <NumberStepper
        name="quantity"
        value={quantity}
        onValueChange={setQuantity}
        min={0}
        max={10}
        step={1}
      />
      <Field.Description>Choose up to ten items.</Field.Description>
    </Field.Root>
  );
};
```

La cancellazione del campo restituisce `null`. Il testo incompleto, come `-` o `+`, rimane modificabile senza riportare un numero non valido finché non viene sostituito o modificato a passi. Per impostazione predefinita, le modifiche numeriche analizzabili restituiscono il valore entro i limiti; la bozza visualizzata viene normalizzata alla perdita del focus. I valori uguali al valore corrente non richiamano di nuovo `onValueChange`.

`onValueCommitted(value, details)` restituisce il valore dopo la conferma di una modifica: alla perdita del focus dopo la digitazione o la cancellazione, al rilascio del puntatore dopo una regolazione tramite pulsante e immediatamente per le regolazioni da tastiera. I relativi dettagli contengono `event` nativo e `reason`. `onValueChange` conserva i dettagli della modifica, inclusi i metodi di annullamento e la direzione facoltativa del passo.

## Convalida dell'applicazione

Imposta `allowOutOfRange` quando l'applicazione necessita del valore analizzato prima di applicare i propri limiti o la propria convalida. `onValueChange` riceve quindi i numeri digitati e incollati al di fuori dell'intervallo. I campi non controllati, o i campi controllati che accettano tali valori, li mantengono alla perdita del focus. I campi controllati che li rifiutano tornano al valore accettato alla perdita del focus. Ad esempio, sostituendo `60` con `45` vengono restituiti `4` e poi `45`, anche quando `min={30}`. L'applicazione può ignorare il valore intermedio senza salvare accidentalmente il minimo.

I pulsanti e le regolazioni da tastiera si fermano comunque a `min` e `max`. La convalida nativa del modulo impedisce l'invio finché un valore accettato è al di fuori di tale intervallo. `allowOutOfRange` è impostato su `false` per impostazione predefinita.

## Limiti e interazione

`min` e `max` sono inclusivi. I pulsanti di incremento e decremento si fermano al limite corrispondente. Freccia su e Freccia giù regolano l'input attivo di `step`, che per impostazione predefinita è `1`. Home e Fine selezionano il limite corrispondente quando fornito; chiama `event.preventBaseUIHandler()` in `onKeyDown` per mantenere invece il comportamento di modifica del testo di un tasto. Lo stesso passo si applica quando si tiene premuto Maiusc o Alt. I valori visualizzati supportano fino a 15 cifre frazionarie; usa un passo positivo entro tale precisione per le regolazioni decimali.

I valori utilizzano cifre latine e visualizzano separatori di raggruppamento a partire da cinque cifre intere, ad esempio `12,500`. Sono accettati i separatori delle migliaia digitati e incollati delle impostazioni locali del browser.

`step` controlla le regolazioni; non arrotonda i valori digitati a un passo. Quando è impostato `min`, la convalida nativa del modulo richiede anche `min` più un multiplo di `step`: con il valore predefinito di `step` pari a `1`, un `2.5` digitato blocca l'invio. Imposta `showButtons={false}` per modificare il testo con lo stesso comportamento da tastiera.

Ogni pulsante ha un nome accessibile predefinito. Usa `decrementLabel` e `incrementLabel` per fornire nomi contestuali o tradotti. Fornisci all'input un `Field.Label` visibile, `aria-label` o `aria-labelledby`.

## Moduli e focus

Usa `name` per includere il valore numerico in un modulo. `form` lo associa a un modulo presente altrove nel documento. I pulsanti di regolazione usano `type="button"`, quindi la regolazione di un valore non invia il modulo. `required` partecipa alla convalida nativa.

Usa un `value` controllato quando l'applicazione deve reimpostare il campo. Il ripristino nativo di un modulo non reimposta lo stato numerico.

`disabled` impedisce le modifiche ed esclude il valore dall'invio del modulo. `readOnly` impedisce le modifiche mantenendo l'input attivabile e il relativo valore disponibile per il modulo.

Gli attributi e i gestori dell'input nativo, `className`, `style`, `ref` e `render` si applicano all'input di testo visibile. Il ref riceve un `HTMLInputElement`; chiama `ref.current?.focus()` per attivarlo. Quando esegui la composizione tramite `render`, inoltra le props e il ref forniti a un input nativo. Personalizza il layout circostante con un elemento separato oppure usa le parti `NumberField.Root` e `NumberField.Group` quando è necessario accedere al wrapper. Combina l'input con `Field.Description` e `Field.Error` per messaggi di guida e convalida.

Il preset usa deliberatamente uno stile compatto, cifre latine, fino a 15 cifre frazionarie, raggruppamento a partire da cinque cifre intere e lo stesso `step` per le regolazioni normali, con Maiusc e con Alt. Queste scelte si applicano solo a `NumberStepper`. La primitiva completa `NumberField` mantiene le opzioni di formattazione e regolazione a passi di Base UI.

## Renderer del componente Front

Le sandbox del renderer React e Preact supportano la digitazione, le regolazioni da tastiera, i limiti, i valori dei moduli, la regolazione tramite puntatore e l'incollaggio sul testo selezionato. La galleria del renderer verifica queste interazioni in entrambi i runtime. Come per `NumberField`, le regolazioni tramite puntatore restituiscono le modifiche, ma la sandbox al momento non fornisce il callback di conferma corrispondente al rilascio del puntatore. Gli host React ordinari mantengono il comportamento di conferma completo.

## Props

**allowOutOfRange** `boolean` (default: false)

Allows onValueChange to receive typed and pasted numbers outside the bounds. Native range validation still applies; buttons and keyboard adjustments remain bounded.

**aria-roledescription** `string` (default: Number field)

A user-friendly description of the input's role for assistive tech. This is a role
description, not an accessible name — use `Field.Label` or `aria-label` to name the control.

**className** `string | ((state: NumberFieldInputState) =\> string | undefined)`

Class applied to the visible input.

**decrementLabel** `string` (default: Decrease value)

Accessible name for the decrement button.

**defaultValue** `number`

Initial number when the field owns its value.

**disabled** `boolean` (default: false)

Disables the input and both buttons, and omits the form value.

**form** `string`

ID of the form that owns the submitted numeric value.

**id** `string`

ID of the visible input. Generated when omitted.

**incrementLabel** `string` (default: Increase value)

Accessible name for the increment button.

**max** `number`

Inclusive maximum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.

**min** `number`

Inclusive minimum. By default, onValueChange reports bounded numbers and out-of-range drafts normalize on blur.

**name** `string`

Name of the numeric value submitted with a form.

**onValueChange** `((value: number | null, eventDetails: NumberFieldRootChangeEventDetails) =\> void)`

Called with the next number or null and event details when the numeric value changes. Clearing reports null; incomplete text does not report a number.

**onValueCommitted** `((value: number | null, eventDetails: NumberFieldRootCommitEventDetails) =\> void)`

Called with the committed number or null and generic event details after an edit is committed. Details contain the native event and reason, without change cancellation methods.

**readOnly** `boolean` (default: false)

Prevents numeric changes while keeping the input focusable.

**ref** `Ref\<HTMLInputElement\>`

Ref to the visible input element.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<DetailedHTMLProps\<InputHTMLAttributes\<HTMLInputElement\>, HTMLInputElement\>, NumberFieldInputState\>`

Composes the visible text input with an element or render callback. Forward the supplied props and ref to an input. Use a separate element to customize the surrounding layout.

**required** `boolean` (default: false)

Requires a numeric value for native form submission.

**showButtons** `boolean` (default: true)

Shows the decrement and increment buttons.

**step** `number` (default: 1)

Amount added or subtracted by the buttons and arrow keys.

**style** `CSSProperties | ((state: NumberFieldInputState) =\> CSSProperties | undefined)`

Inline styles applied to the visible input.

**value** `number | null`

Controlled numeric value. Use null for an empty field.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.