# Spin Button

> A number input with step buttons.

## Examples

### Basic

```vue
<script setup lang="ts">
const seats = ref(3);
</script>

<template>
  <UiSpinButton v-model="seats" label="Seats" :min="1" :max="50" hint="Between 1 and 50." />
</template>
```

### Decimal step

Values round to the step's precision.

```vue
<script setup lang="ts">
const opacity = ref(0.8);
</script>

<template>
  <UiSpinButton v-model="opacity" label="Opacity" :min="0" :max="1" :step="0.05" />
</template>
```

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | — | Id for the control; generated with `useId()` when omitted. |
| `min` | `number` | `Number.NEGATIVE_INFINITY` | Lowest value. Home jumps here. |
| `max` | `number` | `Number.POSITIVE_INFINITY` | Highest value. End jumps here. |
| `step` | `number` | `1` | Arrow-key and button increment; PageUp/PageDown move ten steps. Its decimals set the rounding. |
| `hint` | `string` | — | Help text under the control, announced as its description. |
| `label` | `string` | — | Visible label, linked to the control. |
| `optional` | `boolean` | `false` | Appends the `optional` translation to the label. |
| `disabled` | `boolean` | `false` | Disables the control. |
| `error` | `string \| boolean` | — | `true` marks the control invalid; a string also shows it as the message, replacing the hint. |
| `modelValue` | `number` | — | The value. `undefined` while the input is empty. |

| Event | Payload | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: number \| undefined]` | `v-model:modelValue` update. |

| Slot | Props | Description |
| --- | --- | --- |
| `decrement` | — | Decrease button icon. |
| `increment` | — | Increase button icon. |

## Styling

- Parts (`[data-part="…"]`): `field`, `field-label`, `field-optional`, `spinbutton`, `spinbutton-decrement`, `spinbutton-input`, `spinbutton-increment`, `field-message`
- State attributes: `data-field-error`, `data-spinbutton-error`, `data-spinbutton-disabled`, `data-field-tone`

## Keyboard

| Keys                    | Action            |
| ----------------------- | ----------------- |
| `↑` / `↓`               | Step up / down    |
| `Page Up` / `Page Down` | Ten steps         |
| `Home` / `End`          | Minimum / maximum |

## Accessibility

- The buttons repeat while held and are skipped by Tab.
- Values are clamped and rounded on blur.