Stacks Composables

Stacks Composables

154 reactive composables for STX templates. A fixed set of them is available bare, listed below; everything else needs an explicit import from @stacksjs/composables.

The stx runtime decides this, not browser-auto-imports.json. That manifest feeds an ambient .d.ts and nothing reads it at build time, so it says what the compiler accepts and not what the browser has; the two disagree in both directions (stacksjs/stacks#2585).

This page said "All are auto-imported in STX templates", which is the mistake AGENTS.md carries a scar about under "200+ composables": an agent reaching for a name on that authority writes a template that does not run, and reads the failure as a framework bug.

What you can write bare in a template

useAsync, useClickOutside, useColorMode, useCounter, useDark, useDebounce, useDebouncedValue, useEventListener, useFetch, useFocus, useHead, useInterval, useLocalStorage, useMutation, useQuery, useRef, useRoute, useSearchParams, useSeoMeta, useSessionStorage, useStore, useThrottle, useTimeout, useToggle, useWebSocket.

Everything else needs an explicit import, and that is most of what the sections below list:

import { useStorage } from '@stacksjs/composables'

buddy typecheck will not tell you which is which, and currently disagrees with the browser in both directions (stacksjs/stacks#2585). storage/framework/browser-auto-imports.json feeds an ambient .d.ts, so the compiler accepts every name it declares - and only five of its 27 use* are in the runtime. useStorage, useNow, useDateFormat, useForm and the use*Store composables typecheck and then throw a ReferenceError during setup, which takes the page down rather than failing the one call. In the other direction useLocalStorage, useColorMode, useCounter and useMediaQuery all work in a template and tsc rejects them.

The list above is the runtime's, so it is the one that predicts whether the page loads.

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

• Only the names listed above are available bare in an STX template, and they come from the stx runtime, not from browser-auto-imports.json - that manifest is compile-time only and disagrees with the runtime in both directions (stacksjs/stacks#2585). Everything else needs import { … } from '@stacksjs/composables'
• 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