syringe-slider

An animated SVG syringe slider component for React. Fill, drag, step, and inject — all with smooth motion and customizable liquid color.

Features

• Drag to set — drag the barrel up/down to set a value
• Click needle to auto-fill — click the needle tip to start auto-filling (accelerates over time); click again to stop
• Step buttons — increment/decrement by a configurable step via the imperative ref API
• Push animation — animate the plunger down to zero (inject) via ref or prop
• Controlled & uncontrolled — works both ways, just like native <input>
• Customizable — liquid color, max value, step size
• TypeScript — full type definitions included
• Zero CSS — fully self-contained SVG, no stylesheet required

Installation

npm install syringe-slider

Peer dependencies (install separately if not already present):

npm install react react-dom

syringe-slider also depends on motion for animations:

npm install motion

Quick start

import SyringeSlider from 'syringe-slider';

export default function App() {
  return (
    <div style={{ width: 80, height: 400 }}>
      <SyringeSlider />
    </div>
  );
}

Sizing: The component renders a pure SVG with viewBox="0 0 200 1000". Give the wrapper a fixed width and height — the SVG will scale to fill it while preserving the aspect ratio.

Usage

Uncontrolled (no value prop)

The component tracks its own internal state. Provide an onChange callback to observe changes.

<SyringeSlider
  max={100}
  stepSize={5}
  liquidColor="#ef4444"
  onChange={(value) => console.log(value)}
/>

Controlled (with value prop)

Lift the value into your own state. The component never changes it on its own.

const [dose, setDose] = useState(0);

<SyringeSlider
  max={10}
  stepSize={0.5}
  liquidColor="#06b6d4"
  value={dose}
  onChange={setDose}
/>

Imperative ref API

Use a ref to call stepUp(), stepDown(), or triggerPush() from outside the component.

import SyringeSlider, { type SyringeSliderRef } from 'syringe-slider';

const ref = useRef<SyringeSliderRef>(null);

<SyringeSlider ref={ref} max={20} stepSize={1} value={value} onChange={setValue} />

<button onClick={() => ref.current?.stepDown()}>−</button>
<button onClick={() => ref.current?.stepUp()}>+</button>
<button onClick={() => ref.current?.triggerPush()}>Inject</button>

Push via prop

Increment pushTrigger to fire the push animation without a ref.

const [pushTrigger, setPushTrigger] = useState(0);

<SyringeSlider
  max={10}
  value={dose}
  onChange={setDose}
  pushTrigger={pushTrigger}
/>

<button onClick={() => setPushTrigger((t) => t + 1)}>Administer</button>

API

Props — SyringeSliderProps

| Prop | Type | Default | Description | |---|---|---|---| | max | number | 10 | Maximum value of the slider. The syringe is full when value === max. | | stepSize | number | 1 | How much stepUp() / stepDown() change the value. Also controls the number of tick marks on the barrel (capped at 20). | | liquidColor | string | "#ec4899" | Any valid CSS color for the liquid fill (hex, rgb, hsl, named). | | value | number | — | Controlled value. When provided, the component is in controlled mode and will not update its internal state. Must be between 0 and max. | | onChange | (value: number) => void | — | Called whenever the value changes (drag, step, push, auto-fill). In uncontrolled mode the value is already committed; in controlled mode you must update value yourself. | | pushTrigger | number | 0 | Increment this number by any amount to trigger a push (inject) animation. The component compares to the previous value and fires once per change. |

Ref API — SyringeSliderRef

Access via useRef<SyringeSliderRef>() and passing the ref to the component.

| Method | Description | |---|---| | stepUp() | Increase the value by stepSize, clamped to max. Animated. | | stepDown() | Decrease the value by stepSize, clamped to 0. Animated. | | triggerPush() | Animate the plunger from the current value down to 0 (inject). |

Interaction model

| Interaction | What happens | |---|---| | Click needle | Start auto-fill (value increases, speed accelerates). Click again to stop. | | Drag barrel | Set value directly by dragging up/down. | | stepUp() / stepDown() | Animated step change. | | triggerPush() / pushTrigger++ | Animated push to zero. |

Examples

The examples/ directory contains ready-to-use snippets:

| File | Description | |---|---| | 01-basic.tsx | Minimal uncontrolled setup | | 02-controlled.tsx | Controlled value with onChange | | 03-ref-api.tsx | stepUp, stepDown, triggerPush via ref | | 04-push-trigger.tsx | Push animation via pushTrigger prop | | 05-multiple.tsx | Multiple syringes with different configs |

Development

# Install dependencies
npm install

# Run demo app (Vite dev server)
npm run dev

# Build the library
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Publishing to npm

# 1. Set your name/email in package.json (author, repository, homepage)
# 2. Login to npm
npm login

# 3. Publish
npm publish

The prepublishOnly script runs npm run build automatically before publishing.

License

MIT