Skip to content

Repository files navigation

svelte-use logo

@ariefsn/svelte-use

A collection of 100+ Svelte 5 runes-first utility composables.
No stores. No external dependencies. SSR-safe. Fully typed.

GitHub npm version npm downloads Svelte 5 TypeScript


Features

⚡ Svelte 5 Runes Built for $state, $derived, $effect — no stores
🌲 Tree-shakable Import only what you use
🔒 Fully typed First-class TypeScript, no any
🌐 SSR safe All browser APIs are guarded
📦 Zero deps No runtime dependencies
🧹 Auto cleanup Listeners removed on component destroy

Installation

npm install @ariefsn/svelte-use
# or
pnpm add @ariefsn/svelte-use
# or
bun add @ariefsn/svelte-use

Requires Svelte 5 as a peer dependency.


Utilities

Animation

Composable Description
useAnimate Reactive Web Animations API wrapper
useRafFn Run a callback on every animation frame
useParallax Parallax effect based on pointer or device tilt
useTransition Animated numeric transitions with easing

Async

Composable Description
useFetch Reactive fetch with loading/error state
useWebSocket Reactive WebSocket with auto-reconnect
useAsyncState Reactive async/promise state with loading/error
useEventSource Server-sent events; the browser handles reconnection
useBroadcastChannel Cross-tab messaging by structured clone
useAsyncQueue Run async tasks with bounded concurrency

Time

Composable Description
useInterval Reactive interval counter
useIntervalFn Run a callback on an interval
useNow Reactive current Date
useTimeout Reactive timeout flag
useTimeoutFn Run a callback after a delay
useTimeoutPoll Poll a callback with timeout-based intervals
useTimestamp Reactive current timestamp (ms)

State

Composable Description
useToggle Reactive boolean toggle
useCounter Reactive counter with inc/dec/reset
usePrevious Track previous value of any reactive getter
useSorted Reactive sorted copy of an array
useCycleList Cycle through a list reactively
useCountdown Countdown timer with start/stop/reset
useTimeAgo Human-readable relative time string
useAutoResetState State that auto-resets to default after delay
useDefaultState State with fallback for null/undefined
useLastChanged Timestamp of last reactive value change
useTrackHistory Undo/redo history for reactive values
useHistoryState State with built-in undo/redo history
useStateMachine Typed finite state machine, inferred from the config
useOffsetPagination Pagination state that self-corrects when totals shrink
useConfirmDialog Confirmation flow as a single await

Reactivity

Composable Description
useDebounce Debounce any reactive getter
useWatch Watch reactive values with current/previous args
useWhenever Watch that fires only when value becomes truthy
useUntil Await a reactive value reaching a condition
useCloned Deep copy of a reactive value, for edit buffers

Browser – Keyboard & Scroll

Composable Description
useMagicKeys Reactive keyboard state via Proxy — single keys or combos
useKeyModifier Track Ctrl/Shift/Alt/Meta state
useScroll Scroll position, direction, edge arrival
useScrollLock Lock/unlock body scroll
useInfiniteScroll Load more content as a container nears its edge

Browser – Pointer & Drag

Composable Description
useMouse Viewport-relative pointer position
useMousePressed Detect mouse button press state
useMouseInElement Pointer position relative to an element
useDraggable Full-featured draggable with axis, bounds, handles

Browser – Observers

Composable Description
useElementSize Reactive element dimensions via ResizeObserver
useElementBounding Reactive full bounding box, position included
useIntersectionObserver Visibility detection via IntersectionObserver
useResizeObserver Raw ResizeObserver with callback
useMutationObserver DOM mutation observation

Browser – Sensors

Composable Description
useMediaQuery Reactively track whether a CSS media query matches
useWindowSize Reactive viewport dimensions
useIdle Detect user idle state
useNetwork Network Information API (downlink, RTT, effectiveType)
useGeolocation Reactive geolocation via watchPosition
useBreakpoints Reactive responsive breakpoints
useBrowserLocation Reactive browser location (URL, hash, search)
useNavigatorLanguage Reactive navigator language
useOnline Reactive online/offline status
usePageLeave Detect when user leaves the page
useDocumentVisibility Reactive document visibility state
useWindowFocus Track whether browser window is focused
useDeviceMotion Device acceleration and rotation data
useDeviceOrientation Device physical orientation (alpha/beta/gamma)
useDevicePixelRatio Reactive device pixel ratio for Retina detection
useScreenOrientation Screen orientation and angle, with locking
useGamepad Gamepad state, polled only while one is connected
useScrollbarWidth Measure scrollbar width of an element

Browser – Storage

Composable Description
useStorage Reactive Web Storage (local or session)
useLocalStorage Reactive localStorage with SSR safety
useIndexedDB Reactive IndexedDB with CRUD & querying
useBase64 Reactive Base64 encode/decode
useObjectUrl Reactive object URL from Blob/File
useSessionStorage Reactive sessionStorage with SSR safety

Browser – Interaction

Composable Description
useClickOutside Detect clicks outside an element
useDropZone Drag-and-drop zone with file/data support
useElementHover Detect hover state of an element
useFocus Reactive focus state of an element
useActiveElement Track currently focused element globally
useLongPress Long press gesture detection
useStartTyping Detect typing on non-editable elements
useTextareaAutosize Grow a textarea to fit its content
useSwipe Touch swipe gesture detection

Performance

Composable Description
useFps Reactive frames-per-second counter
useThrottleFn Throttle any function
useDebounceFn Debounce any function
useWebWorkerFn Run a self-contained function off the main thread
useMemoize Cache a function's results by its arguments, with LRU

Virtualization

Composable Description
useVirtualList Efficient virtual list rendering

Web APIs

Composable Description
useClipboard Reactive clipboard read/write
useBattery Reactive Battery Status API
useSpeechRecognition Reactive Web Speech Recognition API
useEyeDropper EyeDropper API for color picking
useFileDialog Programmatic file input dialog
useShare Native Web Share API
useVibrate Vibration API
useWebNotification Desktop notifications API
usePermission Browser Permissions API
useWakeLock Screen Wake Lock API
useFullscreen Display any element fullscreen, Escape-aware
useImage Preload an image and track its load state
useSpeechSynthesis Text-to-speech, with async voice loading handled
useFileSystemAccess Read and write real files (Chromium only)
useSupported SSR-safe one-shot feature detection
useEventListener Generic event listener with cleanup
useTextDirection Track/set text directionality
useTextSelection Track text selection

Browser – Appearance

Composable Description
useColorMode Colour mode with auto resolution, persistence and sync
usePreferredDark Whether the OS requests a dark colour scheme
usePreferredColorScheme OS colour scheme as dark / light / no-preference
usePreferredReducedMotion Whether the OS requests reduced motion
usePreferredContrast OS contrast preference, including forced colours
useCssVar Read and write a CSS custom property

Browser – Document

Composable Description
useTitle Read and write document.title, restored on destroy
useFavicon Read and write the favicon, adopting an existing link
useStyleTag Inject a <style> element, deduplicated by id
useScriptTag Load an external script, deduplicated across call sites

Browser – Media

Composable Description
useUserMedia Camera and microphone capture, device switching, preview mirroring
useDisplayMedia Screen capture that notices the browser's "Stop sharing"
useDevicesList Media devices grouped by kind, refreshed on devicechange

Head & SEO

Composable Description
useSeo Layered SEO metadata as a builder, rendered into <svelte:head>
Seo Component that renders useSeo output — the only component here

Browser – Navigation

Composable Description
useNavigationGuard Navigation guard with confirm/cancel — requires SvelteKit
useUrlSearchParams Reactive URL query parameters, with history and hash modes

Note: useNavigationGuard is the only composable here that is not plain-Svelte. It imports beforeNavigate and goto from $app/navigation, so it works in SvelteKit apps only; @sveltejs/kit is not a declared peer dependency. Every other composable in this library runs in any Svelte 5 app.


Composable Reference

useToggle

Reactive boolean toggle.

import { useToggle } from '@ariefsn/svelte-use';

const { value, toggle, set } = useToggle();
// value → false
toggle(); // value → true
set(false); // value → false
Return Type Description
value boolean (reactive) Current boolean state
toggle () => void Flips the value
set (v: boolean) => void Sets the value explicitly

useCounter

Reactive counter with increment, decrement, and reset.

import { useCounter } from '@ariefsn/svelte-use';

const { value, inc, dec, reset } = useCounter(0);
inc(); // value → 1
inc(5); // value → 6
dec(3); // value → 3
reset(); // value → 0
Return Type Description
value number (reactive) Current counter value
inc (delta?: number) => void Increment by delta (default 1)
dec (delta?: number) => void Decrement by delta (default 1)
reset () => void Reset to initial value

usePrevious

Tracks the previous value of any reactive getter. Returns undefined until the tracked value changes for the first time.

import { usePrevious } from '@ariefsn/svelte-use';

let count = $state(0);
const prev = usePrevious(() => count);
// prev() → undefined
count = 1;
// prev() → 0
count = 2;
// prev() → 1
Parameter Type Description
getter () => T Reactive getter function to observe

Returns a () => T | undefined getter.


useDebounce

Delays a reactive value until the source stops changing for the specified duration.

import { useDebounce } from '@ariefsn/svelte-use';

let query = $state('');
const debounced = useDebounce(() => query, 500);
// debounced() updates only after 500 ms of inactivity
Parameter Type Default Description
getter () => T — Reactive getter to debounce
delay number 300 Delay in milliseconds

Returns a () => T getter.


useLocalStorage

Reactive localStorage with SSR safety. Values are serialised with JSON.stringify / JSON.parse. Falls back to initial in non-browser environments or on parse errors.

import { useLocalStorage } from '@ariefsn/svelte-use';

const theme = useLocalStorage<'light' | 'dark'>('theme', 'light');
theme.set('dark'); // persists to localStorage
theme.value; // 'dark'
Parameter Type Description
key string localStorage key
initial T Fallback when key is absent or in SSR
Return Type Description
value T (reactive) Current stored value
set (v: T) => void Update and persist the value

useIndexedDB

Reactive IndexedDB utility with full CRUD, querying, and filtering. SSR-safe — all operations are no-ops on the server. Values survive page refreshes and browser restarts.

import { useIndexedDB } from '@ariefsn/svelte-use';

interface Note {
	id?: number;
	text: string;
	done: boolean;
}

const db = useIndexedDB<Note>('my-app', 'notes');

// CRUD
await db.add({ text: 'Buy milk', done: false }); // returns generated key
await db.get(1); // Note | undefined
await db.getAll(); // Note[]
await db.update({ id: 1, text: 'Buy milk', done: true });
await db.remove(1);
await db.clear(); // delete all records

// Reactive state (updated automatically after every mutation)
db.items; // Note[]   — all records
db.loading; // boolean
db.error; // Error | null

// Filtering
const pending = await db.query((n) => !n.done); // Note[]

Options

Parameter Type Default Description
dbName string — IndexedDB database name
storeName string — Object store name
options.version number 1 Schema version (increment to migrate)
options.keyPath string 'id' Primary key field name
options.autoIncrement boolean true Auto-generate numeric keys

Returns

Property / Method Type Description
items T[] (reactive) All stored records; refreshed after every mutation
loading boolean (reactive) true while an async operation is in flight
error Error | null (reactive) Last error, or null
add(record) Promise<IDBValidKey | undefined> Insert record; returns generated key
get(key) Promise<T | undefined> Fetch single record by primary key
getAll() Promise<T[]> Fetch all records and sync items
update(record) Promise<void> Replace record (must include key field)
remove(key) Promise<void> Delete record by primary key
query(filter) Promise<T[]> Return records matching a predicate (doesn't modify items)
clear() Promise<void> Delete all records

useSorted

Returns a reactive sorted copy of an array. Never mutates the source.

import { useSorted } from '@ariefsn/svelte-use';

let items = $state([3, 1, 4, 1, 5]);
const sorted = useSorted(() => items);
// sorted() → [1, 1, 3, 4, 5]

const desc = useSorted(
	() => items,
	(a, b) => b - a
);

useCycleList

Cycle through a list reactively. Wraps around at both ends.

import { useCycleList } from '@ariefsn/svelte-use';

const cycle = useCycleList(['light', 'dark', 'system']);
cycle.state(); // → 'light'
cycle.next(); // → 'dark'
cycle.prev(); // → 'light'
cycle.setIndex(2);

useCountdown

Countdown timer with start/stop/reset.

import { useCountdown } from '@ariefsn/svelte-use';

const timer = useCountdown(60); // 60s at 1s intervals
timer.start();
timer.count(); // → 60, 59, …, 0
timer.isActive(); // → true
timer.stop();
timer.reset();

useTimeAgo

Reactive human-readable relative time string.

import { useTimeAgo } from '@ariefsn/svelte-use';

const ago = useTimeAgo(() => new Date('2024-01-01'));
ago(); // → "1 year ago"

useMagicKeys

Track any key or combination via a Proxy.

import { useMagicKeys } from '@ariefsn/svelte-use';

const keys = useMagicKeys();
keys['ctrl+s'](); // → true while Ctrl+S is held
keys['shift'](); // → true while Shift is held

useKeyModifier

Track a specific modifier key state.

import { useKeyModifier } from '@ariefsn/svelte-use';

const ctrl = useKeyModifier('ctrl'); // 'ctrl' | 'shift' | 'alt' | 'meta'
ctrl(); // → true while Ctrl is held

useScroll

Scroll position, direction flags, edge detection for any scrollable element or window.

import { useScroll } from '@ariefsn/svelte-use';

const scroll = useScroll(); // window
const elScroll = useScroll(() => myEl, { offset: { bottom: 20 } });

scroll.y(); // → number
scroll.isScrolling(); // → boolean
scroll.arrivedState.bottom(); // → boolean
scroll.directions.down(); // → boolean
scroll.scrollTo({ top: 0 });

useMouse

Tracks viewport-relative pointer position.

import { useMouse } from '@ariefsn/svelte-use';

const mouse = useMouse();
mouse.x(); // → number
mouse.y(); // → number
mouse.sourceType(); // → 'mouse' | 'touch' | null

useMousePressed

Detects whether any mouse button is held.

import { useMousePressed } from '@ariefsn/svelte-use';

const pressed = useMousePressed();
pressed(); // → boolean

useDraggable

Full-featured draggable with axis constraints, bounds, handles, and callbacks.

import { useDraggable } from '@ariefsn/svelte-use';

const drag = useDraggable(() => el, {
	axis: 'x',
	initialValue: { x: 100, y: 100 },
	onEnd: (pos) => console.log(pos)
});

drag.x(); // → number
drag.isDragging(); // → boolean
drag.style(); // → "transform: translate(100px, 0px);"

useElementSize

Reactively tracks element dimensions via ResizeObserver.

import { useElementSize } from '@ariefsn/svelte-use';

const size = useElementSize(() => el);
size.width(); // → number
size.height(); // → number

useIntersectionObserver

Viewport visibility detection.

import { useIntersectionObserver } from '@ariefsn/svelte-use';

const { isIntersecting, stop } = useIntersectionObserver(() => el, { threshold: 0.5 });
isIntersecting(); // → boolean

useResizeObserver

Raw ResizeObserver wrapper with automatic cleanup.

import { useResizeObserver } from '@ariefsn/svelte-use';

const { stop } = useResizeObserver(
	() => el,
	(entry) => {
		console.log(entry.contentRect.width);
	}
);

useMutationObserver

Observes DOM mutations on any node.

import { useMutationObserver } from '@ariefsn/svelte-use';

const { stop } = useMutationObserver(
	() => el,
	(mutations) => {
		for (const m of mutations) console.log(m.type);
	},
	{ childList: true, subtree: true }
);

useIdle

Detect user inactivity.

import { useIdle } from '@ariefsn/svelte-use';

const { isIdle, reset } = useIdle(5000); // idle after 5s
isIdle(); // → boolean

useNetwork

Reactive Network Information API.

import { useNetwork } from '@ariefsn/svelte-use';

const net = useNetwork();
net.effectiveType(); // → '4g' | '3g' | undefined
net.downlink(); // → Mbps | undefined
net.saveData(); // → boolean | undefined

useGeolocation

Reactive geolocation via watchPosition.

import { useGeolocation } from '@ariefsn/svelte-use';

const geo = useGeolocation({ enableHighAccuracy: true });
geo.coords()?.latitude; // → number | null
geo.error(); // → GeolocationPositionError | null
geo.isSupported(); // → boolean

useFetch

Reactive fetch wrapper with loading/error state.

import { useFetch } from '@ariefsn/svelte-use';

const { data, loading, error, execute } = useFetch<User[]>('/api/users');
// data() → User[] | null
// loading() → boolean
// error() → Error | null

useWebSocket

Reactive WebSocket with auto-reconnect.

import { useWebSocket } from '@ariefsn/svelte-use';

const ws = useWebSocket('wss://echo.example.com');
ws.send('hello');
ws.data(); // → last received message
ws.status(); // → 'OPEN' | 'CLOSED' | 'CONNECTING'

useAnimate

Reactive Web Animations API wrapper.

import { useAnimate } from '@ariefsn/svelte-use';

const { animate, stop } = useAnimate(() => el);
animate([{ opacity: 0 }, { opacity: 1 }], { duration: 300 });

useParallax

Parallax effect based on pointer position or device tilt.

import { useParallax } from '@ariefsn/svelte-use';

const { tilt, roll } = useParallax(() => containerEl);
// tilt() → number  (−0.5 to 0.5)
// roll() → number  (−0.5 to 0.5)

useTransition

Animated numeric transitions with easing.

import { useTransition } from '@ariefsn/svelte-use';

let target = $state(0);
const animated = useTransition(() => target, { duration: 500 });
// animated() smoothly interpolates to target

useInterval

Reactive interval counter.

import { useInterval } from '@ariefsn/svelte-use';

const { counter, pause, resume } = useInterval(1000);
counter(); // → increments every second

useNow

Reactive current Date.

import { useNow } from '@ariefsn/svelte-use';

const now = useNow();
now(); // → Date (updated every second by default)

useTimestamp

Reactive current timestamp in milliseconds.

import { useTimestamp } from '@ariefsn/svelte-use';

const ts = useTimestamp();
ts(); // → number (ms since epoch)

useBreakpoints

Reactive responsive breakpoints.

import { useBreakpoints } from '@ariefsn/svelte-use';

const bp = useBreakpoints({ sm: 640, md: 768, lg: 1024 });
bp.lg(); // → true if viewport ≥ 1024px
bp.between('sm', 'lg')(); // → boolean

useClipboard

Reactive clipboard read/write.

import { useClipboard } from '@ariefsn/svelte-use';

const { text, copy, copied } = useClipboard();
copy('Hello!');
copied(); // → true for 1.5s after copy

useBattery

Reactive Battery Status API.

import { useBattery } from '@ariefsn/svelte-use';

const battery = useBattery();
battery.level(); // → 0–1
battery.charging(); // → boolean

useVirtualList

Efficient virtual list rendering for large datasets.

import { useVirtualList } from '@ariefsn/svelte-use';

const { list, containerProps, wrapperProps } = useVirtualList(items, { itemHeight: 40 });
// list() → only the visible slice of items

Developing

bun install
bun run dev

To run tests:

bun run test

Building & Publishing

# build the library
bun run build

# publish to npm
npm publish --access public

Links

Star History

Star History Chart

License

MIT