# NumberField

Campo de número com mais e menos.

Use quando o valor tem passo e limite conhecidos: quantidade, parcelas, dias de
prazo. Para dinheiro, o `MaskedInput` com molde de moeda diz mais, porque ali o
que importa e a pontuacao e não o passo.

O `Input` cru continua servindo para número solto. A diferença aqui e que seta
do teclado, rolagem e os botões respeitam `min`, `max` e `step`, o campo nunca
chega num valor que o formulário rejeita depois.

```tsx
<Field>
  <FieldLabel>Parcelas</FieldLabel>
  <NumberField defaultValue={3} min={1} max={12} />
  <FieldDescription>De 1 a 12, sem juros.</FieldDescription>
</Field>
```

## No React Native

Traduz: o `@rivocode/ui-native` exporta `NumberField` - vira stepper (menos, valor, mais), que é o idioma do toque. A API não é a mesma do web (no nativo tudo é controlado), e a [tabela de paridade](/react-native) diz o que muda peça a peça.

## Importação

```tsx
import { NumberField } from '@rivocode/ui'
```

## Exemplos

### Com rótulo

```tsx
import { Field, FieldDescription, FieldLabel, NumberField } from '@rivocode/ui'

export function WithLabel() {
  return (
    <Field className="w-56">
      <FieldLabel>Parcelas</FieldLabel>
      <NumberField aria-label="Quantidade" defaultValue={3} min={1} max={12} />
      <FieldDescription>De 1 a 12, sem juros.</FieldDescription>
    </Field>
  )
}
```

### Desabilitado

```tsx
import { Field, FieldDescription, FieldLabel, NumberField } from '@rivocode/ui'

export function Disabled() {
  return (
    <div className="w-56">
      <NumberField aria-label="Quantidade" defaultValue={1} disabled />
    </div>
  )
}
```

## Props

| Prop | Tipo | Obrigatória | Desde | O que faz |
| --- | --- | --- | --- | --- |
| `allowOutOfRange` | `boolean` |  | 0.4.0 | When true, direct text entry may be outside the `min`/`max` range without clamping, so native range underflow/overflow validation can occur. |
| `allowWheelScrub` | `boolean` |  | 0.4.0 | Whether to allow the user to scrub the input value with the mouse wheel while focused and hovering over the input. |
| `defaultValue` | `number` |  | 0.4.0 | The uncontrolled value of the field when it's initially rendered. |
| `disabled` | `boolean` |  | 0.4.0 | Whether the component should ignore user interaction. |
| `form` | `string` |  | 0.4.0 | Identifies the form that owns the hidden input. |
| `inputRef` | `Ref<HTMLInputElement>` |  | 0.4.0 | A ref to access the hidden input element. |
| `largeStep` | `number` |  | 0.4.0 | The large step value of the input element when incrementing while the shift key is held. |
| `locale` | `LocalesArgument` |  | 0.4.0 | The locale of the input element. |
| `max` | `number` |  | 0.4.0 | The maximum value of the input element. |
| `min` | `number` |  | 0.4.0 | The minimum value of the input element. |
| `name` | `string` |  | 0.4.0 | Identifies the field when a form is submitted. |
| `numberFormat` | `NumberFormatOptions` |  | 0.5.0 | As opcoes do `Intl.NumberFormat`. |
| `onValueChange` | `((value: number \| null, eventDetails: NumberFieldRootChangeEventDetails) => void)` |  | 0.4.0 | Callback fired when the number value changes. |
| `onValueCommitted` | `((value: number \| null, eventDetails: NumberFieldRootCommitEventDetails) => void)` |  | 0.4.0 | Callback function that is fired when the value is committed. |
| `placeholder` | `string` |  | 0.4.0 |  |
| `readOnly` | `boolean` |  | 0.4.0 | Whether the user should be unable to change the field value. |
| `render` | `ComponentRenderFn<HTMLProps, NumberFieldRootState> \| ReactElement<unknown, string \| JSXElementConstructor<any>>` |  | 0.4.0 | Allows you to replace the component's HTML element with a different tag, or compose it with another component. |
| `required` | `boolean` |  | 0.4.0 | Whether the user must enter a value before submitting a form. |
| `size` | `"lg" \| "md" \| "sm"` |  | 0.4.0 |  |
| `smallStep` | `number` |  | 0.4.0 | The small step value of the input element when incrementing while the alt key is held. |
| `snapOnStep` | `boolean` |  | 0.4.0 | Whether the value should snap to the nearest step when incrementing or decrementing. |
| `step` | `number \| "any"` |  | 0.4.0 | Amount to increment and decrement with the buttons and arrow keys, or to scrub with pointer movement in the scrub area. |
| `value` | `number \| null` |  | 0.4.0 | The raw numeric value of the field. |

Além dessas: repassa `className`, `style`, `id` e os demais atributos do elemento raiz.

## Ver também

- [Autocomplete](/componentes/autocomplete.md)
- [Calendar](/componentes/calendar.md)
- [Checkbox](/componentes/checkbox.md)
- [CheckboxGroup](/componentes/checkbox-group.md)
- [ColorPicker](/componentes/color-picker.md)
- [Combobox](/componentes/combobox.md)
- [Convenções da biblioteca](/convencoes.md): Provider, tokens e as regras que valem para toda peça
- [Índice completo](/llms.txt)