svelte-pasito

A tiny, themeable, dependency-free fluid stepper component for Svelte 5.

Live demo →

This is a Svelte port of pasito by @joshpuckett, which originally ships React and Vue implementations. All credit for the design, API, and CSS goes to the original project — this package reimplements it for Svelte 5, using runes and reactive classes in place of hooks/composables. See LICENSE for full attribution.

Install

npm install svelte-pasito

Usage

<script lang="ts">
	import { Stepper } from 'svelte-pasito';

	let active = $state(0);
</script>

<Stepper count={5} {active} onStepClick={(index) => (active = index)} />

Autoplay

useAutoPlay drives active on a timer and hands back filling/fillDuration to feed into <Stepper> for the progress-fill animation. Its inputs are getters (() => value) rather than plain values, since the underlying AutoPlayController needs to read the current value at the moment it fires, not a snapshot from when it was constructed.

<script lang="ts">
	import { Stepper, useAutoPlay } from 'svelte-pasito';

	let active = $state(0);
	const count = 5;

	const autoplay = useAutoPlay({
		count: () => count,
		active: () => active,
		onStepChange: (index) => (active = index),
		stepDuration: () => 3000
	});
</script>

<Stepper
	{count}
	{active}
	onStepClick={(index) => (active = index)}
	filling={autoplay.filling}
	fillDuration={autoplay.fillDuration}
	onfocusin={autoplay.handleFocusIn}
	onfocusout={autoplay.handleFocusOut}
/>

<button onclick={autoplay.toggle}>
	{autoplay.playing ? 'Pause' : 'Play'}
</button>

onfocusin/onfocusout are optional: with them, playback pauses while keyboard focus is inside the stepper and resumes when it leaves (only if it was playing before).

If you'd rather manage the instance yourself, AutoPlayController is exported directly too — useAutoPlay(options) is just new AutoPlayController(options).

Props

Prop	Type	Default	Description
count	number	—	Total number of steps
active	number	—	Zero-based active step index
onStepClick	(index: number) => void	—	Called when a step is clicked
orientation	'horizontal' | 'vertical'	'horizontal'	Layout direction
maxVisible	number	—	Max visible steps before windowing kicks in
transitionDuration	number	500	Step transition duration, in ms
easing	string	—	CSS transition timing function
className	string	—	Extra class for the container
filling	boolean	—	Whether the active step is filling
fillDuration	number	—	Fill animation duration, in ms
onfocusin	(event: FocusEvent) => void	—	Focus entered the stepper (pass autoplay.handleFocusIn)
onfocusout	(event: FocusEvent) => void	—	Focus left a step (pass autoplay.handleFocusOut)

Theming

Override appearance with CSS custom properties on .pasito-container (or pass a className and scope the overrides to it):

.pasito-container {
	--pill-dot-size: 8px;
	--pill-active-width: 24px;
	--pill-gap: 6px;
	--pill-bg: rgba(0, 0, 0, 0.12);
	--pill-active-bg: rgba(0, 0, 0, 0.8);
	--pill-fill-bg: rgba(255, 255, 255, 0.45);
	--pill-container-bg: rgba(0, 0, 0, 0.04);
	--pill-container-radius: 999px;
	--pill-container-border: rgba(0, 0, 0, 0.06);
}

Accessibility

Steps render as role="tab" buttons with aria-selected, a roving tabindex, and descriptive aria-labels, and all transitions respect prefers-reduced-motion.

Keyboard (when onStepClick is passed):

Key	Action
← →	Previous / next step (horizontal; wraps around)
↑ ↓	Previous / next step (vertical; wraps around)
Home / End	First / last step
Enter / Space	Select the focused step
Tab	Into and out of the stepper (lands on the active step)

With autoplay, wire onfocusin/onfocusout (see above) so playback pauses while focus is inside the stepper. A play/pause <button> toggles with Space like any button.

Developing

npm install
npm run dev       # dev server
npm run check     # svelte-check
npm run lint       # prettier --check . && eslint .
npm run build      # builds the library (svelte-package + publint)

src/lib is the published library; src/routes is the showcase/preview app.

License

MIT — see LICENSE. Includes attribution to the original pasito project by Josh Puckett.