Velocity Carousel

Velocity Carousel

An overlapping artwork deck with a larger central frame, active project captions and direct navigation. Six original fashion portraits of fictional adults appear by default.

Installation

Keep src, assets and component.json together after downloading the React package. The wrapper imports its stylesheet. The core has no runtime dependencies; the wrapper uses the React installation in your application. The default sans typeface uses bundled OFL-licensed Inter; serif and monospace choices use system fonts.

import { VelocityCarousel } from './velocity-carousel/src/react';

export default function Projects() {
  return <VelocityCarousel sizing="standalone" height={720} />;
}

Default sizing="fill" fills a parent with an explicit height. sizing="standalone" uses height, bounded to 360–1400 pixels. className and style apply to the React host. Card geometry responds to the component's container width, including nested layouts. The deck uses mobile proportions below 640px, tablet proportions at 640–1023px and desktop proportions from 1024px. Card size scales those proportions; available width and short stage heights bound the result.

Focus deck

Straight, overlapping cards keep the active project in a larger central frame, with a centered lower caption and quiet dot navigation. Content, geometry, colors and typography remain configurable.

import { VelocityCarousel } from './velocity-carousel/src/react';

export default function Collection() {
  return (
    <VelocityCarousel
      sizing="standalone"
      height={680}
      images={['portrait-04', 'portrait-02', 'portrait-05']}
      titles={['Warm Front', 'Low Light', 'Night Shift']}
      descriptions={['Amber light against a dark silhouette.', 'Quiet confidence in charcoal and soft grey.', 'Copper hair and a trace of motion.']}
      links={['https://example.com/projects/warm-front', 'https://example.com/projects/low-light', 'https://example.com/projects/night-shift']}
      initialIndex={0}
      radius={32}
      background="#e9ede5"
      controlColor="#21382b"
    />
  );
}

Content and artwork

images accepts up to 12 entries. Use bundled keys portrait-01 through portrait-06, HTTPS image URLs ending in PNG, JPG, JPEG, WebP, GIF or AVIF, or base64 raster data URLs. An empty list restores the included six-image sequence. Each entry is limited to two million characters; HTTPS URLs are limited to 2048 characters. SVG, insecure HTTP, URL credentials, whitespace in URLs and arbitrary local paths are rejected.

titles, descriptions and links map by position. Missing titles and descriptions use the included copy at that position, repeating when necessary. Explicit empty text stays empty. Missing or empty links omit the CTA. All default links are illustrative example.com destinations; replace them with your own HTTPS project pages. ctaLabel="" omits all project links. Long titles and descriptions stay within their caption panel; keep titles under roughly 35 characters for an untruncated phone caption.

Custom artwork loads through normal browser requests. When an image fails after mounting, it is replaced once with local Arclen artwork. Card geometry stays reserved. Bundled artwork is embedded in delivery builds and needs no external image requests. Images use a square crop, centered within the frame. Frames use translucent glass with a soft highlight and backdrop blur; the image itself stays sharp. frameColor tints the glass, and borderWidth sets its thickness. Browsers without backdrop blur retain the translucent surface.

Navigation and motion

Click an exposed neighboring card or select an item control. Previous/next controls become visible when they receive keyboard focus. The carousel wraps at either end through arrows and keyboard input. The deck follows a horizontal drag directly. Release selects a nearby item using recent pointer speed, normalized by the configured card spacing; holding before release removes the flick momentum. Long drags can cross several items. A new grab interrupts the current motion at its rendered position. Gestures have soft resistance at either end and stay within the collection. Vertical gestures retain page scrolling. Horizontal trackpad input and Shift+wheel move the deck and snap after a 120ms input gap. Ordinary vertical wheel input, zoom gestures and scrolling within the item navigator remain native. Dragging a project link suppresses its subsequent pointer click; an intentional click follows the link in the current tab.

Focus the carousel or one of its controls to use Left/Right, Home or End. Inactive project links leave the tab order. The active image has its project title as alt text; a live status announces the selected project. Navigation controls remain available when project links are omitted. showDots=false hides the per-item navigator; keyboard arrows, gestures and focusable previous/next controls still work. Compact, separated item targets surround the dot marks; the item navigator scrolls horizontally when needed.

Click and keyboard navigation use a 1000ms cubic-bezier(.4, 0, .2, 1) transition. Its new caption waits 120ms, then fades for 700ms with the same curve; the previous caption leaves immediately. Cards interpolate their scale from the current value to the new selection, so intermediate cards keep their inactive size during a long jump. Drag and wheel releases use a critically damped spring, capped at 700ms, preserving release speed and current position; their caption waits 60ms and fades over 160ms. Every new action continues from the current rendered position and scale. There is no autoplay, repeating timer or animation frame loop at rest. Reduced motion and controller pause change selection immediately. Offscreen or hidden-document suspension settles the current selection and cancels its frame. Returning to the scene has no elapsed-time catch-up. Hover never advances or pauses the deck. An inactive card grows by 5% over 300ms under a mouse pointer; the active frame keeps its selected size.

Geometry and surface updates retain the existing cards. Content updates rebuild the collection inside its existing root and return an internal focus position to the carousel. Changing initialIndex selects the new starting item; shorter image lists clamp the current selection. The React paused prop calls the same pause/resume policy while preserving selection. React prop removal restores the manifest default. Core updates merge partial settings.

Vanilla

<div id="projects"></div>

import { mount } from './velocity-carousel/src/core';
import './velocity-carousel/src/styles.css';

const host = document.querySelector<HTMLElement>('#projects');
if (!host) throw new Error('Missing project host');
const carousel = mount(host, { sizing: 'standalone', height: 720 });

// Later in your application:
carousel.update({ radius: 40 });
carousel.pause();
carousel.resume();
// Call carousel.destroy() when removing the host.

Core exports defaults, resolveSettings(input), render(settings, id?) and mount(host, settings, id?). mount owns the host's children and returns update, pause, resume and destroy. Invalid settings throw before altering the scene. destroy is idempotent and releases owned listeners, observers, pointer capture and pending frames and gesture timers. Pass distinct IDs when using render directly for multiple instances. Mounted instances receive unique IDs automatically.

Server output contains the selected project artwork and its active link. HTML downloads include CSS, local media, JavaScript and a no-JavaScript poster. Keep the downloaded bundle together when deploying at the site root or a nested path.

Settings

The manifest owns these defaults and bounds. Numeric values must be finite integers. Colors accept six- or eight-digit hex or transparent. Caption color controls the overlay text. Choose readable color combinations for your artwork. height applies only to standalone sizing.

| Setting | Type | Default | Bounds / options | | --- | --- | --- | --- | | images | string-list | ["portrait-01","portrait-02","portrait-03","portrait-04","portrait-05","portrait-06"] | up to 12 entries, 2000000 characters each | | titles | string-list | ["Afterimage","Low Light","Sideways","Warm Front","Night Shift","Last Light"] | up to 12 entries, 100 characters each | | descriptions | string-list | ["A portrait shaped by warmth and movement.","Quiet confidence in charcoal and soft grey.","A turn of the head, held in colour.","Amber light against a dark silhouette.","Copper hair and a trace of motion.","The last warm light before evening."] | up to 12 entries, 220 characters each | | links | string-list | ["https://example.com/projects/afterimage","https://example.com/projects/low-light","https://example.com/projects/sideways","https://example.com/projects/warm-front","https://example.com/projects/night-shift","https://example.com/projects/last-light"] | up to 12 entries, 2048 characters each | | ctaLabel | text | "View project" | up to 48 characters | | initialIndex | number | 3 | 0–11 | | cardSize | number | 380 | 240–520 | | spacing | number | 196 | 100–320 | | radius | number | 56 | 0–100 | | borderWidth | number | 10 | 0–20 | | showDots | boolean | true | — | | background | color | "#f5f5f5" | — | | textColor | color | "#ffffff" | — | | frameColor | color | "#ffffff" | — | | controlColor | color | "#111111" | — | | titleSize | number | 28 | 18–42 | | font | select | "system" | system, serif, mono | | sizing | select | "fill" | fill, standalone | | height | number | 720 | 360–1400 | | label | text | "Editorial portrait carousel" | up to 160 characters |

Artwork rights

The six bundled fashion portraits are original Arclen artwork created through Higgsfield using GPT Image 2.5 in October 2026. Production masters were requested at maximum quality and the 4K tier. The supplied 1200px WebP derivatives preserve the square composition and are encoded at quality 90. Exact hashes and rights are in ASSETS.json and the artwork documents under assets/.