Types

use-split-view is written in TypeScript with full type exports. Everything is tree-shakeable.

useSplitView types

UseSplitViewOptions

interface UseSplitViewOptions {
  /** Split orientation. @default "horizontal" */
  direction?: SplitViewDirection
  /** Initial split position as a percentage (0–100). @default 50 */
  initialSplit?: number
  /** Minimum allowed zoom level. @default 0.1 */
  minScale?: number
  /** Maximum allowed zoom level. @default 50 */
  maxScale?: number
  /** Multiplier for pan speed (mouse wheel only). @default 1 */
  panSpeed?: number
  /** Multiplier for zoom speed (mouse wheel only). @default 1 */
  zoomSpeed?: number
  /** Controlled view state. When provided, the hook becomes controlled. */
  viewState?: ViewState
  /** Callback fired on every view change. Required for controlled mode. */
  onViewStateChange?: (view: ViewState) => void
  /** Pass-through options forwarded to the underlying useZoomPinch instance. */
  zoom?: SplitViewZoomOptions
}

UseSplitViewReturn

interface UseSplitViewReturn {
  containerRef: RefObject<HTMLDivElement | null>
  split: number
  setSplit: (value: number) => void
  view: ViewState
  setView: (v: ViewState, opts?: AnimationOptions) => void
  centerZoom: (targetZoom: number, opts?: AnimationOptions) => void
  resetView: (opts?: AnimationOptions) => void
  isAnimating: boolean
  direction: SplitViewDirection
  isLocked: boolean
  setIsLocked: (locked: boolean) => void
  containerSize: { w: number; h: number }
  naturalSize: { w: number; h: number } | null
  setNaturalSize: (w: number, h: number) => void
  fitScale: number
  displaySize: { w: number; h: number }
  displayZoomPct: number
  getPaneState: (part: "start" | "end") => SplitPaneState
  handleProps: HandleProps
  splitCSSValue: string
  zoomApi: SplitViewZoomApi
}

SplitViewDirection

type SplitViewDirection = "horizontal" | "vertical"

SplitPaneState

interface SplitPaneState {
  /** CSS clip-path string for this pane */
  clipPath: string
  /** CSS transform string for the zoom/pan layer */
  transform: string
  /** Style for the content sizing layer */
  contentStyle: CSSProperties
}

SplitViewZoomOptions

Pass-through options for the underlying useZoomPinch instance. It’s UseZoomPinchOptions minus the fields useSplitView owns (containerRef, scale/speed limits, view-state, enabled):

type SplitViewZoomOptions = Omit<
  UseZoomPinchOptions,
  | "containerRef"
  | "minScale" | "maxScale"
  | "panSpeed" | "zoomSpeed"
  | "viewState" | "onViewStateChange"
  | "enabled"
>

Use it to enable bounds, inertia, keyboard navigation, rotation, double-tap, snap-to-grid, activation keys, and more. See Advanced Zoom Options.

SplitViewZoomApi

The advanced imperative helpers from the same useZoomPinch instance that drives the panes (view, setView, centerZoom, resetView, isAnimating are exposed directly on UseSplitViewReturn and omitted here):

type SplitViewZoomApi = Omit<
  UseZoomPinchReturn,
  "view" | "setView" | "centerZoom" | "resetView" | "isAnimating"
>

Includes zoomIn, zoomOut, zoomTo, panTo, panBy, fitToRect, fitToContent, zoomToElement, rotateTo, rotateBy, snapZoom, screenToContent, contentToScreen.

Re-exported from use-zoom-pinch

ViewState

interface ViewState {
  x: number
  y: number
  zoom: number
  /** Rotation angle in degrees. @default 0 */
  rotation?: number
}

AnimationOptions

interface AnimationOptions {
  /** Enable animated transition. @default false */
  animate?: boolean
  /** Animation duration in milliseconds. @default 300 */
  duration?: number
  /** Easing function. @default easeOut */
  easing?: EasingFunction
  /** Skip bounds clamping, axis locking, and snap-to-grid (setView only). @default false */
  skipConstraints?: boolean
}

type EasingFunction = (t: number) => number

Advanced useZoomPinch types

These come along for the ride when you use the re-exported useZoomPinch directly:

• UseZoomPinchOptions — all options for the underlying zoom/pinch hook (bounds, gestures, inertia, keyboard, rotation, snap, activation keys, wheelMode, axis, cursor management, etc.)
• UseZoomPinchReturn — imperative helpers (zoomIn, zoomOut, zoomTo, panTo, panBy, fitToRect, fitToContent, zoomToElement, rotateTo, rotateBy, snapZoom, screenToContent, contentToScreen, isAnimating)
• BoundsOptions — minX, maxX, minY, maxY, mode: "clamp" | "bounce", bounceFactor
• GesturesOptions — toggles for pan, zoom, rotate
• InertiaOptions — enabled, friction
• DoubleTapOptions — enabled, mode: "zoomIn" | "reset" | "toggle", step
• RotationOptions — minAngle, maxAngle, snapLevels
• KeyboardOptions — enabled, panStep, zoomStep, rotateStep
• CursorOptions — enabled, idle, dragging, zooming
• ActivationKeyOptions — pan, zoom, rotate key names
• SnapToGridOptions — size, mode: "end" | "always"
• ZoomSnapLevel — number

See the use-zoom-pinch reference for full signatures.

Easing helpers

import { linear, easeOut, easeInOut } from "use-split-view"

Predefined EasingFunction values that pair with AnimationOptions.easing. You can also supply any custom (t: number) => number function.

Geometry helpers

Re-exported from use-zoom-pinch:

import { clamp, distance, angleBetween } from "use-split-view"

clamp(value, min, max)              // clamp a number to [min, max]
distance(x1, y1, x2, y2)            // euclidean distance between two points
angleBetween(x1, y1, x2, y2)        // angle (degrees) of the vector (x1,y1)→(x2,y2)

Handy for building measurement overlays, markers, or custom snap logic on top of the split view.

Importing

// Main hook
import { useSplitView } from "use-split-view"

// Hook types
import type {
  UseSplitViewOptions,
  UseSplitViewReturn,
  SplitViewDirection,
  SplitPaneState,
  SplitViewZoomOptions,
  SplitViewZoomApi,
} from "use-split-view"

// Re-exported view-state types
import type { ViewState, AnimationOptions, EasingFunction } from "use-split-view"

// Re-exported underlying hook
import { useZoomPinch } from "use-split-view"
import type { UseZoomPinchOptions, UseZoomPinchReturn } from "use-split-view"

// Re-exported easing + geometry helpers
import { linear, easeOut, easeInOut, clamp, distance, angleBetween } from "use-split-view"