svelte-wheel-picker 🖱️

iOS-style wheel picker for Svelte 5 with smooth inertia scrolling, infinite loop support, keyboard navigation, and cylindrical 3D effect.

Features

• Svelte 5 runes-based reactivity
• Smooth inertia scrolling with spring physics
• Infinite loop mode
• Cylindrical/drum 3D visual effect
• Full keyboard navigation (arrow keys, Home/End, type-ahead search)
• Controlled and uncontrolled modes
• Disabled options support
• WheelPickerWrapper for multi-wheel layouts (time picker, date picker)
• Headless/unstyled with data attributes for CSS targeting
• Zero runtime dependencies
• TypeScript types included
• SSR safe

Installation

npm

npm install @uinstinct/svelte-wheel-picker

pnpm add @uinstinct/svelte-wheel-picker

yarn add @uinstinct/svelte-wheel-picker

shadcn-svelte

npx shadcn-svelte@latest add https://svelte-wheel-spinner.netlify.app/r/wheel-picker.json

This copies the component source directly into your project under src/lib/components/ui/wheel-picker/.

Quick Start

<script lang="ts">
  import { WheelPicker } from '@uinstinct/svelte-wheel-picker';

  const fruits = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
    { value: 'date', label: 'Date' },
    { value: 'fig', label: 'Fig' },
  ];

  let selected = $state('cherry');
</script>

<WheelPicker
  options={fruits}
  value={selected}
  onValueChange={(v) => { selected = v; }}
/>

Examples

Basic (controlled mode)

<script lang="ts">
  import { WheelPicker } from '@uinstinct/svelte-wheel-picker';

  const options = [
    { value: 'a', label: 'Option A' },
    { value: 'b', label: 'Option B' },
    { value: 'c', label: 'Option C' },
  ];

  let value = $state('a');
</script>

<WheelPicker
  {options}
  {value}
  onValueChange={(v) => { value = v; }}
/>

Infinite loop

<script lang="ts">
  import { WheelPicker } from '@uinstinct/svelte-wheel-picker';

  const fruits = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
  ];

  let selected = $state('apple');
</script>

<WheelPicker
  options={fruits}
  value={selected}
  onValueChange={(v) => { selected = v; }}
  infinite={true}
/>

Cylindrical/drum effect

<script lang="ts">
  import { WheelPicker } from '@uinstinct/svelte-wheel-picker';

  const fruits = [
    { value: 'apple', label: 'Apple' },
    { value: 'banana', label: 'Banana' },
    { value: 'cherry', label: 'Cherry' },
  ];

  let selected = $state('apple');
</script>

<WheelPicker
  options={fruits}
  value={selected}
  onValueChange={(v) => { selected = v; }}
  cylindrical={true}
/>

Multi-wheel with WheelPickerWrapper

<script lang="ts">
  import { WheelPicker, WheelPickerWrapper } from '@uinstinct/svelte-wheel-picker';

  const hourOptions = Array.from({ length: 12 }, (_, i) => ({
    value: String(i + 1).padStart(2, '0'),
    label: String(i + 1).padStart(2, '0'),
  }));

  const minuteOptions = Array.from({ length: 60 }, (_, i) => ({
    value: String(i).padStart(2, '0'),
    label: String(i).padStart(2, '0'),
  }));

  let hour = $state('12');
  let minute = $state('00');
</script>

<WheelPickerWrapper classNames={{ group: 'time-picker' }}>
  <WheelPicker
    options={hourOptions}
    value={hour}
    onValueChange={(v) => { hour = v; }}
  />
  <WheelPicker
    options={minuteOptions}
    value={minute}
    onValueChange={(v) => { minute = v; }}
  />
</WheelPickerWrapper>

<style>
  :global([data-swp-group].time-picker) {
    display: flex;
    flex-direction: row;
    align-items: stretch;
  }
</style>

API Reference

WheelPickerProps<T>

| Prop | Type | Default | Description | |------|------|---------|-------------| | options | WheelPickerOption<T>[] | — | The list of selectable options. Required. | | value | T | undefined | Current value (controlled mode). undefined means no option selected. | | defaultValue | T | undefined | Initial value (uncontrolled mode). | | onValueChange | (value: T) => void | undefined | Callback when value changes. Presence signals controlled mode. | | classNames | WheelPickerClassNames | {} | Per-element CSS class overrides. | | visibleCount | number | 5 | Number of visible option rows. Must be odd. | | optionItemHeight | number | 30 | Height in pixels of each option row. | | dragSensitivity | number | 3 | Pointer drag delta multiplier (affects inertia deceleration). | | scrollSensitivity | number | 5 | Scroll wheel delta multiplier (affects snap animation duration). | | infinite | boolean | false | Enable infinite loop scrolling (wraps at both ends). | | cylindrical | boolean | false | Enable rotating drum/cylinder visual style with faux-3D scaleY compression. |

WheelPickerOption<T>

| Field | Type | Description | |-------|------|-------------| | value | T | The option's value. Must be string or number. | | label | string | Display text rendered in the wheel. | | textValue | string (optional) | Fallback text for type-ahead search when label is not plain text. | | disabled | boolean (optional) | Whether this option is disabled (skipped in navigation). |

WheelPickerWrapperProps

| Prop | Type | Description | |------|------|-------------| | classNames | WheelPickerWrapperClassNames | Per-element CSS class overrides for the wrapper group container. |

WheelPickerWrapperClassNames: { group?: string } — optional CSS class for the outer group container div.

Styling

The library ships no CSS. It is fully headless. Use the classNames prop to assign your own CSS classes, then target elements with your stylesheet.

Data Attributes

All elements expose data attributes for CSS targeting:

| Attribute | Element | Notes | |-----------|---------|-------| | data-swp-wrapper | Outer container of WheelPicker | Always present | | data-swp-option | Each option row | Always present | | data-swp-option-text | Text span inside each option | Always present | | data-swp-selection | Center selection highlight overlay | Always present | | data-swp-selected | Option row | Present with value "true" when the option is currently selected | | data-swp-disabled | Option row | Present with value "true" when the option is disabled | | data-swp-group | Outer container of WheelPickerWrapper | Always present |

CSS Example

/* Make the wheel container draggable */
[data-swp-wrapper].my-wheel {
  width: 200px;
  cursor: grab;
  user-select: none;
  touch-action: none;
}

[data-swp-wrapper].my-wheel:active {
  cursor: grabbing;
}

/* Style the selection highlight */
[data-swp-selection].my-selection {
  background: rgba(59, 130, 246, 0.15);
  border-top: 1px solid rgba(59, 130, 246, 0.3);
  border-bottom: 1px solid rgba(59, 130, 246, 0.3);
}

/* Style each option row */
[data-swp-option].my-option {
  font-size: 16px;
  transition: opacity 0.15s;
}

/* Dim disabled options */
[data-swp-option][data-swp-disabled='true'] {
  opacity: 0.3;
}

/* Bold the selected option */
[data-swp-option][data-swp-selected='true'] {
  font-weight: 600;
}

Pass your class names via the classNames prop:

<WheelPicker
  {options}
  {value}
  onValueChange={(v) => { value = v; }}
  classNames={{
    wrapper: 'my-wheel',
    selection: 'my-selection',
    option: 'my-option',
  }}
/>

Keyboard Navigation

When the wheel picker is focused:

| Key | Action | |-----|--------| | Arrow Up | Move selection up by one | | Arrow Down | Move selection down by one | | Home | Jump to first option | | End | Jump to last option | | Type a character | Type-ahead search: jump to the next option whose label (or textValue) starts with the typed character(s) |

License

MIT