use-split-view

Headless React hook for building split-view side-by-side comparison interfaces with built-in zoom, pan, and pinch-to-zoom support.

Zero styling opinions — you bring the markup, the hook manages all the state and interaction logic.

Live Demo

Features

• Headless — no DOM output, no CSS dependencies, full control over markup
• Split handle dragging with pointer capture
• Synchronized zoom/pan across both panes via use-zoom-pinch
• Trackpad scroll, mouse wheel zoom, touch pinch-to-zoom
• Horizontal and vertical split directions
• Fit-to-container scaling with natural size tracking
• Controlled and uncontrolled view state
• TypeScript-first with full type exports

Installation

npm install use-split-view
# or
pnpm add use-split-view
# or
yarn add use-split-view

react >= 18 is a peer dependency.

Quick Start

import { useSplitView } from "use-split-view"

function ImageComparison() {
  const {
    containerRef,
    getPaneState,
    handleProps,
    setNaturalSize,
    displayZoomPct,
    resetView,
    split,
  } = useSplitView({ direction: "horizontal" })

  const startPane = getPaneState("start")
  const endPane = getPaneState("end")

  return (
    <div
      ref={containerRef}
      style={{
        position: "relative",
        width: "100%",
        height: 500,
        overflow: "hidden",
        touchAction: "none",
        userSelect: "none",
      }}
    >
      {/* Start pane */}
      <div style={{ position: "absolute", inset: 0, clipPath: startPane.clipPath }}>
        <div
          style={{
            width: "100%",
            height: "100%",
            transformOrigin: "top left",
            transform: startPane.transform,
          }}
        >
          <div style={startPane.contentStyle}>
            <img
              src="/before.jpg"
              style={{ width: "100%", height: "100%", objectFit: "fill" }}
              draggable={false}
              onLoad={(e) => {
                const { naturalWidth, naturalHeight } = e.currentTarget
                setNaturalSize(naturalWidth, naturalHeight)
              }}
            />
          </div>
        </div>
      </div>

      {/* End pane */}
      <div style={{ position: "absolute", inset: 0, clipPath: endPane.clipPath }}>
        <div
          style={{
            width: "100%",
            height: "100%",
            transformOrigin: "top left",
            transform: endPane.transform,
          }}
        >
          <div style={endPane.contentStyle}>
            <img
              src="/after.jpg"
              style={{ width: "100%", height: "100%", objectFit: "fill" }}
              draggable={false}
            />
          </div>
        </div>
      </div>

      {/* Drag handle */}
      <div
        {...handleProps}
        style={{
          position: "absolute",
          top: 0,
          bottom: 0,
          left: `${split}%`,
          width: 24,
          transform: "translateX(-50%)",
          cursor: "col-resize",
          zIndex: 10,
        }}
      >
        <div
          style={{
            width: 2,
            height: "100%",
            margin: "0 auto",
            backgroundColor: "white",
            boxShadow: "0 0 4px rgba(0,0,0,0.5)",
          }}
        />
      </div>

      {/* Zoom indicator */}
      <button onClick={resetView} style={{ position: "absolute", top: 8, right: 8, zIndex: 10 }}>
        {displayZoomPct}%
      </button>
    </div>
  )
}

API Reference

useSplitView(options?)

import { useSplitView } from "use-split-view"

Options

| Option | Type | Default | Description | | ------------------- | ---------------------------- | -------------- | -------------------------------------- | | direction | "horizontal" \| "vertical" | "horizontal" | Split direction | | initialSplit | number | 50 | Initial split position (0-100) | | minScale | number | 0.1 | Minimum zoom level | | maxScale | number | 50 | Maximum zoom level | | panSpeed | number | 1 | Pan speed multiplier (mouse wheel) | | zoomSpeed | number | 1 | Zoom speed multiplier (mouse wheel) | | viewState | ViewState | — | Controlled view state { x, y, zoom } | | onViewStateChange | (view: ViewState) => void | — | Callback for controlled mode |

Return Value

| Property | Type | Description | | ---------------- | ------------------------------ | --------------------------------------------- | | containerRef | RefObject<HTMLDivElement> | Attach to the container element | | split | number | Current split position (0-100) | | setSplit | (value: number) => void | Set split position programmatically | | view | ViewState | Current { x, y, zoom } | | setView | (v: ViewState) => void | Set view state directly | | centerZoom | (targetZoom: number) => void | Zoom keeping center as anchor | | resetView | () => void | Reset to { x: 0, y: 0, zoom: 1 } | | direction | SplitViewDirection | Current direction | | isLocked | boolean | Whether zoom/pan is locked (handle drag) | | setIsLocked | (locked: boolean) => void | Lock/unlock zoom/pan manually | | containerSize | { w, h } | Container dimensions in pixels | | naturalSize | { w, h } \| null | Natural content dimensions | | setNaturalSize | (w, h) => void | Set natural dimensions (call on content load) | | fitScale | number | Scale to fit content in container | | displaySize | { w, h } | Display dimensions (naturalSize * fitScale) | | displayZoomPct | number | Zoom as display percentage | | getPaneState | (part) => SplitPaneState | Get clip/transform/style for a pane | | handleProps | object | Spread on the drag handle element | | splitCSSValue | string | CSS value like "50%" |

SplitPaneState

Returned by getPaneState("start" | "end"):

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

ViewState

Re-exported from use-zoom-pinch:

interface ViewState {
  x: number
  y: number
  zoom: number
}

Re-exports

The package re-exports everything from use-zoom-pinch for convenience:

import { useZoomPinch, type UseZoomPinchOptions, type UseZoomPinchReturn } from "use-split-view"

Architecture

The hook follows a layered approach matching the original SplitView component:

Container (containerRef)
├── Pane "start" (clipPath clips to left/top half)
│   └── Transform layer (translate + scale from view)
│       └── Content layer (sized by contentStyle)
├── Pane "end" (clipPath clips to right/bottom half)
│   └── Transform layer (same transform)
│       └── Content layer (same contentStyle)
└── Handle (drag to change split, uses handleProps)

Both panes share the same view state, so zoom and pan are always synchronized. The clipPath on each pane creates the split effect by revealing only the relevant portion.

Content Sizing

When you call setNaturalSize(width, height) (typically in an onLoad handler), the hook:

1. Computes fitScale — the scale needed to fit the content within the container without exceeding its natural size
2. Returns displaySize — the rendered dimensions at fitScale
3. If the natural size changes (e.g., a higher-res image loads), automatically compensates zoom and position to maintain visual continuity

Handle Interaction

The handleProps object includes:

• Pointer capture for smooth dragging even when the cursor leaves the handle
• Automatic zoom/pan locking during drag to prevent conflicts
• Mouse enter/leave locking for hover states

Examples

Vertical Split

const sv = useSplitView({ direction: "vertical" })
// The handle becomes horizontal, content splits top/bottom

Controlled View State

const [view, setView] = useState({ x: 0, y: 0, zoom: 1 })

const sv = useSplitView({
  viewState: view,
  onViewStateChange: setView,
})

Video Comparison

<video
  src="/video-a.mp4"
  autoPlay
  loop
  muted
  playsInline
  style={{ width: "100%", height: "100%", objectFit: "fill" }}
  onLoadedData={(e) => {
    const { videoWidth, videoHeight } = e.currentTarget
    sv.setNaturalSize(videoWidth, videoHeight)
  }}
/>

Zoom Controls

<button onClick={() => sv.centerZoom(sv.view.zoom * 2)}>Zoom In</button>
<button onClick={() => sv.centerZoom(sv.view.zoom / 2)}>Zoom Out</button>
<button onClick={sv.resetView}>Reset</button>
<span>{sv.displayZoomPct}%</span>

Lock Zoom During UI Interaction

<div onMouseEnter={() => sv.setIsLocked(true)} onMouseLeave={() => sv.setIsLocked(false)}>
  {/* Toolbar, dropdown, etc. */}
</div>

License

MIT