stacks-composables

name	stacks-composables
description	Use when creating or using reactive composables in STX templates — 90+ composables for state management, DOM interaction, sensors, animation, browser APIs, async operations, or the complete list of auto-imported composables. Covers @stacksjs/composables.
license	MIT
compatibility	Bun >= 1.3.0, TypeScript
allowed-tools	Read Edit Write Bash Grep Glob

Stacks Composables

90+ reactive composables for STX templates. All are auto-imported in STX templates.

Key Path

• Core package: storage/framework/core/composables/src/

Core Reactive Primitives

// From _shared.ts
type MaybeRef<T> = T | Ref<T>
type MaybeRefOrGetter<T> = T | Ref<T> | (() => T)
unref(val)           // unwrap Ref
toValue(val)         // unwrap Ref or getter
isRef(val)           // type guard

State & Reactivity

• useToggle(initial?) → [Ref<boolean>, toggle]
• useCounter(initial?) → { count, increment, decrement, set, reset }
• useStepper(steps, initial?) → step navigation
• usePrevious(value) → previous value
• useCycleList(list) → cycle through items

Storage

• useStorage(key, defaultValue, storage?) → persistent Ref
• useLocalStorage(key, defaultValue) → localStorage-backed Ref
• useSessionStorage(key, defaultValue) → sessionStorage-backed Ref

Time & Date

• useNow(options?) → Ref<Date> (auto-updating)
• useDateFormat(date, format) → Ref<string>
• useTimeAgo(date) → relative time string
• useTimestamp(options?) → Ref<number>
• useInterval(fn, ms) → interval control
• useIntervalFn(fn, ms) → interval with pause/resume
• useTimeout(ms) → timeout control
• useTimeoutFn(fn, ms) → delayed execution

DOM & Browser

• useWindowSize() → { width, height }
• useWindowScroll() → { x, y }
• useWindowFocus() → Ref<boolean>
• useDocumentVisibility() → Ref<string>
• useFullscreen(el?) → { isFullscreen, enter, exit, toggle }
• useTitle(title) → document title binding
• useFavicon(url) → favicon binding
• useCssVar(prop, el?) → CSS variable binding
• useActiveElement() → currently focused element
• useTextSelection() → selected text
• useTextDirection() → Ref<'ltr' | 'rtl'>
• useNavigatorLanguage() → browser language

Mouse & Touch

• useMouse() → { x, y, sourceType }
• useMouseInElement(el) → mouse position relative to element
• useMousePressed() → { pressed, sourceType }
• usePointer() → pointer events
• useSwipe(el) → swipe detection
• usePointerSwipe(el) → pointer swipe
• useDraggable(el) → make element draggable
• useDropZone(el) → drop zone detection
• onLongPress(el, handler) → long press detection
• onClickOutside(el, handler) → click outside detection

Sensors

• useGeolocation() → { coords, locatedAt, error }
• useDeviceMotion() → acceleration & rotation
• useDeviceOrientation() → alpha, beta, gamma
• useBattery() → { charging, chargingTime, level }
• useDevicePixelRatio() → Ref<number>
• useScreenSafeArea() → safe area insets

Observers

• useIntersectionObserver(el, callback) → visibility detection
• useResizeObserver(el, callback) → size changes
• useMutationObserver(el, callback) → DOM mutations
• useElementBounding(el) → { top, left, width, height }
• useElementVisibility(el) → Ref<boolean>
• useElementHover(el) → Ref<boolean>

Async

• useAsyncState(fn, initial) → { state, isReady, isLoading, error, execute }
• useAsyncQueue(tasks) → sequential async execution
• computedAsync(fn) → async computed value
• computedEager(fn) → immediately evaluated computed

Network

• useFetch(url, options?) → fetch wrapper with reactive state
• useWebSocket(url) → WebSocket connection
• useEventSource(url) → SSE connection
• useOnline() → Ref<boolean> (network status)

Input & Focus

• useFocus(el) → { focused, focus, blur }
• useFocusWithin(el) → any child focused
• useKeyModifier(key) → modifier key state
• usePermission(name) → permission state
• useShare(options) → Web Share API

Utilities

• useDebounceFn(fn, ms) → debounced function
• useThrottleFn(fn, ms) → throttled function
• useDebouncedRef(ref, ms) → debounced ref updates
• useThrottledRef(ref, ms) → throttled ref updates
• watchDebounced(source, callback, ms) → debounced watcher
• watchThrottled(source, callback, ms) → throttled watcher
• watchOnce(source, callback) → one-time watcher
• whenever(source, callback) → watch for truthy
• until(source).toBe(value) → wait for value
• syncRef(refA, refB) → bidirectional sync

Dark Mode

• useDark() → Ref<boolean>
• usePreferredDark() → system preference
• usePreferredColorScheme() → color scheme preference

Media

• useMediaQuery(query) → Ref<boolean>
• usePreferredContrast() → contrast preference
• usePreferredLanguages() → language preferences
• usePreferredReducedMotion() → reduce motion preference

State Patterns

• createEventHook() → typed event hook
• createGlobalState(fn) → shared state across components
• createSharedComposable(fn) → shared composable instance
• refDefault(ref, defaultValue) → ref with default
• refAutoReset(value, ms) → auto-resetting ref
• makeDestructurable(obj, arr) → support both destructuring styles
• useIdle(ms) → user idle detection
• usePageLeave() → detect page leave
• useFps() → frames per second
• useMounted() → Ref<boolean> mount state
• tryOnMounted(fn) → safe onMounted
• useObjectUrl(blob) → object URL with auto-cleanup

Script & Style Injection

• useScriptTag(src, onLoaded?) → inject <script>
• useStyleTag(css) → inject <style>

Math

• useAbs, useAverage, useCeil, useClamp, useFloor, useMax, useMin, usePrecision, useRound, useSum, useTrunc
• and, or, logicNot, logicOr

Gotchas

• All composables are auto-imported in STX templates — no import needed
• NEVER use vanilla JS (var, document.*, window.*) in STX <script> tags
• Only use stx-compatible code: signals, composables, directives
• Auto-imports defined in storage/framework/browser-auto-imports.json
• Many composables require a browser environment (won't work server-side)
• useStorage persists to localStorage by default