Journey Map Scroll

A scroll-driven itinerary with route-following camera motion and pop-out postcards, with configurable stops, copy, fonts, and accent color.

Why this one

The map travels with you instead of sitting above a list. Each postcard originates at its own pin. An original dotted sea, organic coast, mountain contours, and a luminous route tip give the itinerary its own visual language. No map service, tiles, or location data are needed.

How it works

1. An animated ScrollView converts its measured scroll offset into one continuous chapter progress, p, from 0 to 3.
2. Smoothstep poses hold the traveler still within 20% of each chapter. Cubic curves and length-normalized samples keep the traveler aligned with the trimmed route.
3. The camera looks 15% ahead along the route and follows with interruptible springs. All map geometry is in an independent 600-unit coordinate system.
4. Postcards launch from the transformed pin into their lower-screen position. Headline windows finish exiting before the next begins entering.
5. Incoming background photos fade over the previous photo. Top and bottom veils maintain contrast. Fast-scroll route light activates above 600 points per second; the intro also shows the route light.
6. The cover title, brand name, and stop counter use ordinary views and percentage positioning, independently of map measurement. The dotted sea is built only across the visible viewport; the land closes outside all camera poses, and the map window clips to rounded lower corners.
7. The demo drives actual scrolling through the imperative ref, stops on interaction, and resets behind a short black fade. The final action lives inside the scroll content.

Install

npx expo install @shopify/react-native-skia expo-blur expo-image expo-linear-gradient react-native-reanimated react-native-worklets

Configure Reanimated/worklets as required by your Expo project. On web, initialize CanvasKit and load this component lazily after Skia is ready, using your app's Skia web bootstrap. Keep your loading fallback outside the Skia gate if the cover must appear before CanvasKit initializes. This catalog currently gates the entire demo in App.tsx, so its cold-load fallback cannot be replaced from this component folder. Bundle images locally to avoid an empty postcard while a network image loads. Icons: Lucide (ISC); paths are included in icons.ts.

Usage

import { JourneyMapScroll, type JourneyStop } from './journey-map-scroll';

// Supply four original stops, each with its own local image.
const stops: readonly [JourneyStop, JourneyStop, JourneyStop, JourneyStop] = [
  harborStop, cliffStop, valleyStop, mountainStop,
];

<JourneyMapScroll stops={stops} onAction={() => saveTrip()} />;

const journey = useRef<JourneyMapScrollRef>(null);

<JourneyMapScroll
  ref={journey}
  stops={stops}
  title="Coast to Peaks"
  cameraScale={1.6}
  accentColor="#38BDF8"
  fontFamily="Geist_400Regular"
  serifFontFamily="InstrumentSerif_400Regular"
  italicFontFamily="InstrumentSerif_400Regular_Italic"
  monoFontFamily="GeistMono_400Regular"
  onInteraction={stopAutoplay}
  onIndexChange={setSelectedStop}
/>;

// Fractional chapters work too. Autoplay belongs in the caller.
journey.current?.goTo(2, 1900);

Props

Ref methods: goTo(chapter, duration = 1900), replay(), and reset(). Font assets must be loaded by the caller. The component never imports the catalog theme or demo assets.

Compatibility

Targets Expo SDK 58, React Native 0.88.0, Reanimated 4.7.1, worklets 0.13.0, and Skia 2.14.0. Uses Expo Go's installed modules; no new native dependency is introduced. Supports iOS, Android, and web. The demo entry compiles into iOS and Android development bundles (HTTP 200). The photograph uses 20% of container height on taller phones and contracts on compact phones to preserve the two-line headline and data row.

Accessibility

Each chapter includes a descriptive accessible block and a header-role headline. Inactive postcards are hidden from assistive technology. Next-stop buttons provide a tap alternative to scrolling, with 44-point minimum targets. The final button exposes its role and label and scales to 0.97 on press. Reduced motion removes camera travel/zoom, postcard flight, pulse, ambient drift, and trails; chapter arrivals use 200 ms fades. Web scrolling never uses mandatory snap.