Vue API Reference

Complete reference for @reelkit/vue components, composables, and utilities.

Reel

Tag: <Reel>

Props

Prop	Type	Default	Description
count	number	required	Total number of slides
direction	'vertical' \| 'horizontal'	'vertical'	Scroll direction
size	[number, number] \| undefined	undefined	Width and height as [width, height]. When omitted, auto-measures via ResizeObserver
initialIndex	number	0	Starting slide index
loop	boolean	false	Enable infinite loop
transition	TransitionTransformFn	slideTransition	Transition effect function. Built-in: slideTransition, fadeTransition, flipTransition, cubeTransition, zoomTransition
transitionDuration	number	300	Animation duration in ms
swipeDistanceFactor	number	0.12	Swipe threshold (0-1)
enableGestures	boolean	true	Enable touch/mouse drag navigation
enableNavKeys	boolean	true	Enable keyboard arrow key navigation
enableWheel	boolean	false	Enable mouse wheel navigation
wheelDebounceMs	number	200	Wheel event debounce in ms
rangeExtractor	(index: number, count: number) => number[]	defaultRangeExtractor	Custom function to determine which indexes are rendered
keyExtractor	(index: number, indexInRange: number) => string	index => index.toString()	Custom key function for slide rendering (useful with loop)
ariaLabel	string	undefined	Accessible label for the carousel region
reelStyle	Record<string, string \| number>	undefined	Inline styles applied to the root container element
reelClass	string \| Array \| Object	undefined	CSS class(es) applied to the root container element
onNavKeyPress	(increment: -1 \| 1) => void	undefined	Callback prop that replaces the default ArrowUp/ArrowDown navigation. When provided, you implement your own navigation (e.g. call reelRef.value.next()). Omit for default behavior.

Events

Event	Payload	Description
beforeChange	(index: number, nextIndex: number, indexInRange: number)	Emitted before slide transition begins
afterChange	(index: number, indexInRange: number)	Emitted after slide transition completes
slideDragStart	(index: number)	Emitted when a drag gesture starts
slideDragEnd	(index: number)	Emitted when a drag gesture ends (released)
slideDragCanceled	(index: number)	Emitted when a drag gesture is canceled (snap-back)
tap	(event: GestureCommonEvent)	Emitted on a single tap gesture
doubleTap	(event: GestureCommonEvent)	Emitted on a double tap gesture
longPress	(event: GestureCommonEvent)	Emitted when a long press gesture starts
longPressEnd	(event: GestureEvent)	Emitted when a long press gesture ends

Slots

vue-html

Slot	Scoped Props	Description
#item	{ index: number, indexInRange: number, size: [number, number] }	Renders each visible slide. Called for each index in the virtualized range
default	none	Overlay content rendered on top of all slides (indicators, controls, etc.)

ReelExpose

Imperative API exposed via template ref:

vue

Method	Type	Description
next()	() => void	Go to next slide
prev()	() => void	Go to previous slide
goTo(index, animate?)	(number, boolean?) => Promise<void>	Navigate to a specific slide index
adjust()	() => void	Recalculate slide positions (useful after layout change)
observe()	() => void	Start listening to gesture, keyboard, and wheel events
unobserve()	() => void	Stop listening to gesture, keyboard, and wheel events

ReelIndicator

Tag: <ReelIndicator>

Props

Prop	Type	Default	Description
count	number \| undefined	auto	Total number of items. Auto-connected from parent Reel context when nested inside one; pass explicitly when used standalone
active	number \| undefined	auto	Current active index. Auto-connected from parent Reel context when nested inside one; pass explicitly when used standalone
direction	'vertical' \| 'horizontal'	'vertical'	Indicator orientation
radius	number	3	Dot radius in pixels
visible	number	5	Max normal-sized dots visible at once
gap	number	4	Space between dots in pixels
activeColor	string	'#fff'	Active dot color
inactiveColor	string	'rgba(255, 255, 255, 0.5)'	Inactive dot color
edgeScale	number	0.5	Scale factor for edge overflow dots
onDotClick	(index: number) => void	undefined	Custom click handler. When omitted inside a Reel, defaults to navigating to the clicked dot index
indicatorClass	string \| Array \| Object	undefined	CSS class(es) applied to the tablist root element
indicatorStyle	CSSProperties	undefined	Inline styles merged into the tablist root element

Events

Event	Payload	Description
dotClick	(index: number)	Emitted when a dot is clicked; provides the dot index

SwipeToClose

Tag: <SwipeToClose> — Wraps its default slot in a touch-aware container that can be swiped to dismiss.

Props

Prop	Type	Default	Description
direction	'up' \| 'down'	required	Swipe direction to trigger close. Use "up" for lightbox dismiss, "down" for stories dismiss
enabled	boolean	true	Whether the swipe-to-close gesture is active
threshold	number	0.2	Fraction of viewport height required to trigger close (0-1)

Events

Event	Payload	Description
close	()	Emitted when the swipe gesture exceeds the threshold and the close animation completes

Slots

Slot	Description
default	Content to wrap with swipe-to-close gesture handling

RK_REEL_KEY & useReelContext

An InjectionKey<ReelContextValue> provided by <Reel> to its descendants. Used internally by <ReelIndicator> for auto-connect behavior. Use useReelContext() in custom components that need slider context.

vue

Property	Type	Description
index	Signal<number>	Reactive current slide index
count	Signal<number>	Reactive total item count
goTo	(index: number, animate?: boolean) => Promise<void>	Programmatically navigate to a slide

Composables

useBodyLock

Locks the document body scroll when the provided value is true. Uses reference counting so multiple concurrent callers can each lock/unlock independently. Automatically unlocks on unmount.

typescript

Parameter	Type	Description
locked	Ref<boolean> \| boolean	Whether body scroll should be locked. Accepts a reactive ref or a static boolean

useFullscreen

Composable for managing the Fullscreen API with cross-browser support. Exits fullscreen automatically on unmount.

typescript

Return	Type	Description
isFullscreen	Signal<boolean>	Core signal reflecting current fullscreen state (read `.value`)
request	() => Promise<void>	Request fullscreen on the referenced element. If another element is already fullscreen, it is exited first (awaited).
exit	() => Promise<void>	Exit fullscreen
toggle	() => Promise<void>	Toggle fullscreen state

useSoundState

Access the current SoundController from context. Must be called inside a <SoundProvider>. Throws if called outside.

typescript

toVueRef

Bridges a core Subscribable (any Signal from @reelkit/core) into a read-only Vue Ref. Use it whenever you need a core signal value to drive a Vue re-render — direct signal.value reads in render functions or templates are not reactive on their own.

The subscription is auto-disposed via onScopeDispose, so this must be called inside a Vue setup() or other effect-scope-aware context.

typescript

SoundProvider

Tag: <SoundProvider> — Context provider that creates a SoundController instance and provides it to descendants via RK_SOUND_KEY. Renders its default slot transparently.

vue

Accessibility

<Reel> renders as role="region" with aria-roledescription="carousel". Pass aria-label (the prop is ariaLabel in TS) to give the region a screen-reader name. A polite live region announces "Slide N of M" on every slide change. Inactive slides receive the inert attribute so focus and AT navigation skip them.

<ReelIndicator> renders as role="tablist" with roving tabindex on the dots; arrow keys move focus and Enter or Space activates the slide.

Building a custom modal around <Reel>? captureFocusForReturn, createFocusTrap, and getFocusableElements are re-exported from @reelkit/vue for focus return and trap.

Package Exports

All public exports from @reelkit/vue:

typescript