# NumberInput

A numeric text input with optional spin buttons and datalist suggestions.

## Usage

Use standalone, or inside `NumberField`.

```svelte
<NumberInput {...props} />
```

## Anatomy

The `class` attribute values represent part names, and `conditional` indicates elements that are rendered conditionally. Other attributes represent their corresponding props.

```svelte
<span class="whole">
  <button class="left" type="button" conditional: spin === "split">{left}</button>
  <input class="main" type="text" inputmode="decimal" />
  <span class="aux" conditional: spin === "stack">
    <button class="right" type="button">{right}</button>
    <button class="left" type="button">{left}</button>
  </span>
  <button class="right" type="button" conditional: spin === "split">{right}</button>
  <datalist conditional>
    {#each options as option}
      <option value={option}></option>
    {/each}
  </datalist>
</span>
```

## Props

| Name           | Type               | Default       | Description                                                                                                        |
| -------------- | ------------------ | ------------- | ------------------------------------------------------------------------------------------------------------------ |
| `value`        | `number`           | -             | Bindable input value; undefined means empty                                                                        |
| `min`          | `number`           | -             | Lower bound used by spin controls and commit behavior                                                              |
| `max`          | `number`           | -             | Upper bound used by spin controls and commit behavior                                                              |
| `step`         | `number`           | `1`           | Increment used by spin buttons and arrow keys                                                                      |
| `any`          | `boolean`          | `false`       | When true, disables step-grid snapping so any value within min/max is allowed (like `step="any"`); spin buttons still move by `step` |
| `inputmode`    | `<enum>`           | `"decimal"`   | Virtual-keyboard hint on the input; overridable HTML `inputmode`                                                   |
| `spin`         | `<enum>`           | `"none"`      | Spin button layout: none, split, or stack                                                                          |
| `left`         | `Snippet`          | -             | Custom decrement button content                                                                                    |
| `right`        | `Snippet`          | -             | Custom increment button content                                                                                    |
| `options`      | `SvelteSet`        | -             | Numeric datalist suggestions                                                                                       |
| `ariaDecLabel` | `string`           | `"Decrement"` | Accessible label for the decrement button                                                                          |
| `ariaIncLabel` | `string`           | `"Increment"` | Accessible label for the increment button                                                                          |
| `attach`       | `Attachment`       | -             | Svelte attachment on the input                                                                                     |
| `element`      | `HTMLInputElement` | -             | Bindable input element                                                                                             |
| `styling`      | `SVSClass`         | -             | Styling override                                                                                                   |
| `variant`      | `SVSVariant`       | `NEUTRAL`     | Variant                                                                                                            |
Other `HTMLInputAttributes` are passed to `<input>` via rest props; `class` is merged onto the root.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

No automatic switching. When used inside a `NumberField`, the field's variant is inherited via context.

### Default Class Name

`svs-number-input`

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `ArrowUp` | When `spin` is not `"none"`, increments the value by `step`, then clamps and snaps it to the configured range |
| `ArrowDown` | When `spin` is not `"none"`, decrements the value by `step`, then clamps and snaps it to the configured range |
Arrow-key stepping is ignored while IME composition is active. The spin buttons expose pointer-driven increment and decrement controls, but they are removed from the tab order.

### ARIA Roles and Attributes

The component applies these automatically:

- Input (`main`): when `spin` is not `"none"`, `role="spinbutton"`, `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`.
- Input (`main`): `aria-describedby`, `aria-invalid`, and `aria-errormessage` from the surrounding `NumberField` context or passed attributes.
- Spin buttons (`left` / `right`): `aria-label` from `ariaDecLabel` and `ariaIncLabel`.

Provide an accessible name for the input yourself because there is no built-in visible label. Pass `aria-label` or `aria-labelledby` through the rest props, or use `NumberInput` inside a labelled `NumberField`.

## Exports

### Types

```ts
interface NumberInputProps extends Omit<HTMLInputAttributes, "type" | "value" | "min" | "max" | "step" | "pattern" | "list"> {
  value?: number; // bindable; undefined = empty
  min?: number;
  max?: number;
  step?: number; // (1)
  any?: boolean; // (false)
  spin?: "none" | "split" | "stack"; // ("none")
  left?: Snippet<[string]>; // Snippet<[variant]>
  right?: Snippet<[string]>; // Snippet<[variant]>
  options?: SvelteSet<number> | Set<number>;
  ariaDecLabel?: string; // ("Decrement")
  ariaIncLabel?: string; // ("Increment")
  attach?: Attachment<HTMLInputElement>;
  element?: HTMLInputElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL)
  // class & other HTMLInputAttributes are passed to <input> via ...rest (class is merged onto the control)
}
type NumberInputReqdProps = never;
type NumberInputBindProps = "value" | "element";
```

The `NumberInputContext` interface export is used by `NumberField` internally.

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=NumberInputBasic.svelte
<script lang="ts">
  import { NumberInput } from "svseeds";

  let value = $state(12);
  const styling = {
    whole: "inline-flex items-stretch rounded-sm border",
    main: "w-24 px-2 text-center outline-hidden",
    left: "p-2 size-8 stroke-stroke cursor-pointer",
    right: "p-2 size-8 stroke-stroke cursor-pointer",
  };
  const myProps = {
    min: 0,
    max: 100,
    spin: "split" as const,
    inputmode: "numeric" as const,
    styling,
  };
</script>

<NumberInput bind:value {...myProps} />
```
### With Interactive Variant

**Code**

```svelte src=NumberInputPract.svelte
<script lang="ts">
  import { NumberInput } from "svseeds";

  let { variant = $bindable() } = $props();
  let value = $state(-3);

  const variantStyle = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const styling = {
    whole: {
      base: "inline-flex items-stretch rounded-sm border",
      ...variantStyle,
    },
    main: "w-28 px-2 text-center outline-hidden",
    left: "p-1 w-8 h-4 cursor-pointer",
    right: {
      base: "p-1 w-8 h-4 cursor-pointer border-be",
      ...variantStyle,
    },
    aux: {
      base: "flex flex-col border-s",
      ...variantStyle,
    },
  };
  const myProps = {
    min: -100,
    max: 100,
    step: 0.3,
    spin: "stack" as const,
    styling,
  };
</script>

<NumberInput bind:value {variant} {...myProps} />
```