Velocity Scene Slider

A horizontal track of scene cards: each card holds any content, and you switch by dragging sideways or tapping the pill indicator. The interesting part is the release — the drag velocity is handed straight to the page-change spring as its initial velocity, so a fast flick lands fast and a slow push glides over, one continuous velocity curve from finger to rest. While dragging, the pills stretch and shrink with progress, and cards sharpen as they reach the centre. Good for feature tours, onboarding and product walkthroughs.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<VelocitySceneSlider/>

    </div>
  );
}

Installation

Usage

import {
  VelocitySceneSlider,
  type VelocityScene,
} from "@/components/ui/velocity-scene-slider";

const scenes: VelocityScene[] = [
  { id: "inbox", label: "Inbox triage", content: <InboxScene /> },
  { id: "schedule", label: "Scheduling", content: <ScheduleScene /> },
  { id: "board", label: "Team board", content: <BoardScene /> },
];

export function Tour() {
  const [index, setIndex] = React.useState(0);
  return (
    <VelocitySceneSlider
      scenes={scenes}
      index={index}
      onIndexChange={setIndex}
      onRelease={({ velocity }) => console.log(`${Math.round(velocity)} px/s`)}
    />
  );
}

Props

VelocityScene

VelocitySceneRelease

CSS variables

How it works

• Velocity matching: on release the drag velocity is passed unchanged as the page-change spring's velocity. With the same stiffness / damping, a flick and a slow push therefore arrive at different speeds and feel different; indicator and keyboard navigation start from velocity 0
• Page-change rule: velocity wins — if the absolute release velocity exceeds velocityThreshold, the slider moves one page in that direction; otherwise the drag must pass 25% of the card width, or it springs back
• Wrapping: with loop on, flicking past the last card returns to the first. The track then travels far in the opposite direction, and carrying the release velocity would shoot it the wrong way first, so wrapping starts from velocity 0
• Indicator: at rest the active pill is 28px and the others 8px, with a CSS transition; while dragging, the two neighbouring widths are interpolated every frame from continuous progress, so the pill looks stretched
• Scene cards: scale 0.94→1 and opacity 0.6→1 interpolate from the distance to centre; cards are 82% of the container width so neighbours peek in on both sides
• Controlled mode: if the parent does not accept the new index from onIndexChange, the track springs back to the original scene

Accessibility

• The root is role="region" with aria-roledescription="carousel", focusable with Tab and showing a focus-visible ring
• Each card is role="group" with aria-roledescription="slide" and an aria-label of "Scene n of N: name"; off-centre cards are inert, so they are neither focusable nor announced
• Once focused, Left/Right arrows change page and Home/End jump to the first/last scene
• The indicator is a role="tablist"; each pill is a type="button" tab with aria-selected and aria-controls, using a roving tabindex so focus follows arrow-key moves
• The current scene is announced through aria-live="polite"
• With the system "reduce motion" setting on, the post-release spring momentum is disabled and page changes become a 150ms total fade out/in; the pills jump straight to their target width without a transition