Spin Button

Edit a numeric draft directly or change it with increment controls.

Usage

Integer

Accept whole-number drafts and expose increment and decrement controls.

Team seatsAdjust the number of seats included in this workspace.4 seats

Allowed range: 0–20 · Step 1

<!-- Spin Button / Integer -->
<script setup lang="ts">
import { ref } from 'vue'
import { SpinButtonDecrement, SpinButtonIncrement, SpinButtonInput, SpinButtonRoot } from '@sectile/vue/spin-button'

const value = ref('4')
</script>

<template>
  <SpinButtonRoot v-model="value" min="0" max="20" step="1">
    <SpinButtonDecrement aria-label="Decrease">−</SpinButtonDecrement>
    <SpinButtonInput />
    <SpinButtonIncrement aria-label="Increase">+</SpinButtonIncrement>
  </SpinButtonRoot>
</template>

Controlled

Let the parent own the current value and apply accepted changes back to the component.

Release offsetFine-tune the offset in exact half-step increments.1.5 points

Allowed range: -10–10 · Step 0.5

<!-- Spin Button / Controlled -->
<script setup lang="ts">
import { ref } from 'vue'
import { SpinButtonDecrement, SpinButtonIncrement, SpinButtonInput, SpinButtonRoot } from '@sectile/vue/spin-button'

const value = ref('1.5')
</script>

<template>
  <SpinButtonRoot v-model="value" min="-10" max="10" step="0.5">
    <SpinButtonDecrement aria-label="Decrease">−</SpinButtonDecrement>
    <SpinButtonInput />
    <SpinButtonIncrement aria-label="Increase">+</SpinButtonIncrement>
  </SpinButtonRoot>
</template>

Examples

Input recovery

Type a quantity directly; leaving an invalid edit restores the last accepted value.

Retry limitEnter a whole number. Leaving an invalid edit restores the saved quantity.10 retries

Allowed range: 0–20 · Step 1

<!-- Spin Button / Invalid Draft -->
<script setup lang="ts">
import { ref } from 'vue'
import { SpinButtonDecrement, SpinButtonIncrement, SpinButtonInput, SpinButtonRoot } from '@sectile/vue/spin-button'

const value = ref('10')
const draft = ref<string | null>(null)
</script>

<template>
  <SpinButtonRoot v-model="value" min="0" max="20" step="1" @update:draft="draft = $event">
    <SpinButtonDecrement aria-label="Decrease">−</SpinButtonDecrement>
    <SpinButtonInput />
    <SpinButtonIncrement aria-label="Increase">+</SpinButtonIncrement>
  </SpinButtonRoot>
  <p v-if="draft !== null">Leaving an invalid edit restores {{ value }}.</p>
</template>

API

Vue package: @sectile/vue/spin-button

Components

SpinButtonRoot
SpinButtonInput
SpinButtonIncrement
SpinButtonDecrement

Props

`SpinButtonRootProps`

as: TypePrimitiveAsDefault'div'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
defaultDraft: Typestring | nullDefaultnull
Editable draft used for uncontrolled initial state.
defaultValue: Typenumber | stringDefaultundefined
Initial value used when the component owns its state.
disabled: TypebooleanDefaultfalse
Whether interaction is unavailable.
draft: Typestring | nullDefaultundefined
Controlled editable draft before commit.
label: TypestringDefaultundefined
Accessible name announced for the control.
max: Typenumber | stringDefaultRequired
Largest value accepted by the component.
min: Typenumber | stringDefaultRequired
Smallest value accepted by the component.
modelValue: Typenumber | stringDefaultundefined
Current value when state is controlled by the parent.
pageStep: TypenumberDefault10
Larger increment used by Page Up and Page Down.
policies: TypeSpinButtonOptions['policies']Defaultundefined
Behavior policies that customize validation, movement, or selection.
readonly: TypebooleanDefaultfalse
Whether the value can be inspected but not changed.
step: Typenumber | stringDefault1
Smallest value increment accepted by the component.

`SpinButtonInputProps`

as: TypePrimitiveAsDefault'input'
Element or component rendered for this part.
asChild: TypebooleanDefaultfalse
Whether to merge this part into its single child instead of rendering a wrapper.
form: TypestringDefaultundefined
ID of the native form associated with the control.
name: TypestringDefaultundefined
Name used for native form submission.
required: TypebooleanDefaultfalse
Whether the control must contain a valid value before submission.

`SpinButtonTriggerProps`

as: TypePrimitiveAsDefaultundefined
Element or component rendered for this part.
asChild: TypebooleanDefaultundefined
Whether to merge this part into its single child instead of rendering a wrapper.

Slots

`SpinButtonSlotProps`

disabled: Typeboolean
Whether interaction is unavailable.
draft: Typestring | null
Current uncommitted input text.
readonly: Typeboolean
Whether the value can be inspected but not changed.
text: Typestring
Formatted text for the current value.
value: Typestring
Current value exposed by this contract.

Events

`SpinButtonRoot`

update:draft: Payloadstring | null
Emitted when the editable draft changes.
update:modelValue: Payloadstring
Emitted when the component requests a new controlled value.

Other types

`SpinButtonValueChangeHandler`

type SpinButtonValueChangeHandler = (value: string) => void

`SpinButtonDraftChangeHandler`

type SpinButtonDraftChangeHandler = (value: string | null) => void

Parts

Shared scope: [data-scope="spin-button"]. Combine it with a part selector to keep styles local to this component.

Part	Selector	Role	Extra attributes
`root`	`[data-part="root"]`	Defines the component boundary and owns its composed parts.	—
`input`	`[data-part="input"]`	Accepts the editable value or draft.	—
`increment`	`[data-part="increment"]`	Increases the value by one configured step.	—
`decrement`	`[data-part="decrement"]`	Decreases the value by one configured step.	—

Keyboard interaction

Key	Behavior
`Arrow Right` / `Arrow Up`	Increase the value by one step.
`Arrow Left` / `Arrow Down`	Decrease the value by one step.
`Home` / `End`	Move to the minimum or maximum value.
`Page Up` / `Page Down`	Change the value by the configured page step when supported.

Accessibility

The input exposes spinbutton value metadata while increment and decrement remain named native controls.

See the corresponding WAI-ARIA pattern for the host accessibility contract.

Spin Button ​

Usage ​

Integer ​

Controlled ​

Examples ​

Input recovery ​

API ​

Props ​

SpinButtonRootProps ​

SpinButtonInputProps ​

SpinButtonTriggerProps ​

Slots ​

SpinButtonSlotProps ​

Events ​

SpinButtonRoot ​

Other types ​

SpinButtonValueChangeHandler ​

SpinButtonDraftChangeHandler ​

Parts ​

Keyboard interaction ​

Accessibility ​