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

> Edita un número con límites opcionales y botones para incrementar o reducir.

## Resumen

`NumberStepper` es el preajuste compacto y práctico creado a partir de [NumberField](https://docs.twenty.com/es/ui/primitives/input/number-field.md). Combina una entrada de texto numérica con botones opcionales para reducir e incrementar. Impórtalo desde `twenty-ui/components/input`. Usa `NumberField` cuando necesites opciones de configuración regional o formato, distintos pasos de modificadores, arrastre o composición independiente de partes.

**Light**

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

**Dark**

[Ejemplo de 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)

## "Uso"

```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>
);
```

## Opciones visuales

Compare los estados predeterminado, con límites, deshabilitado, de solo lectura y no válido, con o sin botones de incremento.

**Light**

[Límites y estados del selector numérico (light)](https://storybook.twenty.com/iframe.html?id=ui-input-numberstepper--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Límites y estados del selector numérico (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)

## Valor no controlado

Usa `defaultValue` para establecer la cantidad inicial. La entrada gestiona los cambios posteriores.

```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>
);
```

## Valor controlado

Pasa un número o `null` mediante `value` y actualízalo en `onValueChange` para gestionar la misma cantidad en el estado de React. La devolución de llamada recibe el siguiente valor numérico y los detalles del 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>
  );
};
```

Al borrar el campo, se informa de `null`. El texto incompleto, como `-` o `+`, sigue siendo editable sin informar de un número no válido hasta que se sustituye o se ajusta mediante un paso. De forma predeterminada, las ediciones numéricas analizables informan del valor limitado; el borrador mostrado se normaliza al perder el foco. Los valores iguales al valor actual no vuelven a llamar a `onValueChange`.

`onValueCommitted(value, details)` informa del valor después de confirmar una edición: al perder el foco tras escribir o borrar, al soltar el puntero tras un ajuste con botón e inmediatamente para los ajustes de teclado. Sus detalles contienen el `event` nativo y `reason`. `onValueChange` conserva los detalles del cambio, incluidos los métodos de cancelación y la dirección de ajuste opcional.

## Validación de la aplicación

Establece `allowOutOfRange` cuando la aplicación necesite el valor analizado antes de aplicar sus propios límites o validación. Entonces, `onValueChange` recibe números escritos y pegados que están fuera del intervalo. Los campos no controlados, o los campos controlados que aceptan esos valores, los conservan al perder el foco. Los campos controlados que los rechazan vuelven a su valor aceptado al perder el foco. Por ejemplo, sustituir `60` por `45` informa de `4` y después de `45`, incluso cuando `min={30}`. La aplicación puede ignorar el valor intermedio sin guardar accidentalmente el mínimo.

Los botones y los ajustes de teclado siguen deteniéndose en `min` y `max`. La validación nativa de formularios impide el envío mientras un valor aceptado esté fuera de ese intervalo. `allowOutOfRange` tiene como valor predeterminado `false`.

## Límites e interacción

`min` y `max` son inclusivos. Los botones de incremento y reducción se detienen en el límite correspondiente. Flecha arriba y Flecha abajo ajustan la entrada enfocada en `step`, cuyo valor predeterminado es `1`. Inicio y Fin seleccionan el límite correspondiente cuando se proporciona; en su lugar, llama a `event.preventBaseUIHandler()` en `onKeyDown` para mantener el comportamiento de edición de texto de una tecla. Se aplica el mismo paso cuando se mantiene pulsada Mayús o Alt. Los valores mostrados admiten hasta 15 dígitos fraccionarios; usa un paso positivo dentro de esa precisión para ajustes decimales.

Los valores usan dígitos latinos y muestran separadores de agrupación a partir de cinco dígitos enteros, como `12,500`. Se aceptan los separadores de agrupación de la configuración regional del navegador escritos y pegados.

`step` controla los ajustes; no redondea los valores escritos a un paso. Cuando se establece `min`, la validación nativa de formularios también requiere `min` más un múltiplo de `step`: con el valor predeterminado de `step` de `1`, un `2.5` escrito bloquea el envío. Establece `showButtons={false}` para editar texto con el mismo comportamiento de teclado.

Cada botón tiene un nombre accesible predeterminado. Usa `decrementLabel` e `incrementLabel` para proporcionar nombres contextuales o traducidos. Proporciona a la entrada un `Field.Label`, `aria-label` o `aria-labelledby` visible.

## Formularios y foco

Usa `name` para incluir el valor numérico en un formulario. `form` lo asocia con un formulario ubicado en otra parte del documento. Los botones de ajuste usan `type="button"`, por lo que ajustar un valor no envía el formulario. `required` participa en la validación nativa.

Usa un `value` controlado cuando tu aplicación necesite restablecer el campo. Un restablecimiento nativo del formulario no restablece el estado numérico.

`disabled` impide los cambios y excluye el valor del envío del formulario. `readOnly` impide los cambios y mantiene la entrada enfocable y su valor disponible para el formulario.

Los atributos y controladores de entrada nativos, `className`, `style`, `ref` y `render` se aplican a la entrada de texto visible. La ref recibe un `HTMLInputElement`; llama a `ref.current?.focus()` para enfocarlo. Al componer mediante `render`, reenvía las props y la ref proporcionadas a una entrada nativa. Personaliza el diseño circundante con un elemento independiente o usa las partes `NumberField.Root` y `NumberField.Group` cuando se requiera acceso al contenedor. Combina la entrada con `Field.Description` y `Field.Error` para mensajes de orientación y validación.

El preajuste usa deliberadamente un estilo compacto, dígitos latinos, hasta 15 dígitos fraccionarios, agrupación a partir de cinco dígitos enteros y el mismo `step` para los ajustes normales, con Mayús y con Alt. Estas opciones se aplican solo a `NumberStepper`. La primitiva completa `NumberField` conserva las opciones de formato y ajuste de Base UI.

## Renderizador de componentes del front-end

Los entornos aislados del renderizador de React y Preact admiten escritura, ajustes de teclado, límites, valores de formulario, ajustes con puntero y pegado sobre texto seleccionado. La galería del renderizador verifica estas interacciones en ambos entornos de ejecución. Al igual que con `NumberField`, los ajustes con puntero informan de cambios, pero el entorno aislado no entrega actualmente la devolución de llamada de confirmación correspondiente al soltar el puntero. Los hosts normales de React conservan el comportamiento completo de confirmación.

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