react-mobile-interactions

@splitin/react-mobile-interactions

Swipe, edge-back, overlays, and native-feeling motion for React.

Hub · Docs · Publishing · Swipe · Use cases · Back · Careers

www.splitin.net/tech-stack/open-internal-tools/react-mobile-interactions

Mobile interactions that feel native — package first, product later

Reusable React primitives for swipe gestures, edge-back navigation, overlay back layers, route transitions, and motion presets. V1 is package-only: install it, ship it, keep versioning it.

Built internally, open sourced so others can use the same gestures SplitIn uses. A tool specialist owns this folder end to end. It can stay MIT and later also power a hosted SplitIn experience.

• Swipe tabs: left forward, right back; inputs and maps ignored by default.
• Overlay back stack: highest priority layer wins.
• Edge-swipe back: router-agnostic, haptic when available.
• Out of the box: Framer Motion presets that respect prefers-reduced-motion.

Table of contents

• Getting started
• Use cases
• Swipe tabs
• Overlay back layers
• Edge-swipe back
• Route transition
• Motion presets
• Careers

Getting started

npm install @splitin/react-mobile-interactions framer-motion

Peer dependencies: react, react-dom, framer-motion.

From this hub (source only; dist/ is gitignored):

git clone https://github.com/splitintech/open-internal-tools.git
cd open-internal-tools/react-mobile-interactions
npm install
npm run build
npm test

Work in sync with other contributors and agents. PRs stay in react-mobile-interactions/.

Use cases

Ten ways developers integrate @splitin/react-mobile-interactions into a React or PWA app:

1. Listing detail tabs — swipe between photos, details, and activity with useSwipeableTabs without stealing taps from buttons.
2. React Router edge-back — MobileEdgeBackHandler + navigate(-1) for an iOS-style left-edge pop.
3. Filter / sort bottom sheet — register the sheet on the overlay back stack so Android/iOS back closes it first.
4. Modal above sheet — two useMobileBackLayer priorities; dialog wins, then the sheet.
5. Onboarding carousel — swipe forward/back across steps; ignore inputs so form fields still type.
6. Inbox vs thread — swipe between list and conversation panes in a messaging PWA.
7. Map + list dual pane — bind swipe on the list; maps, canvases, and iframes stay ignored by default.
8. Checkout stepper — swipe between cart, address, and pay; canStart blocks back when the flow is complete.
9. Settings / profile routes — wrap pages in MobileRouteTransition for sheet-up motion with nativeSprings.smooth.
10. Accessible dialogs — use nativeDialogVariants / shouldAnimate() so reduced-motion users skip transforms.

Swipe tabs

import { useSwipeableTabs } from "@splitin/react-mobile-interactions";

function MobileTabs({ tab, setTab }: { tab: "details" | "activity"; setTab: (tab: "details" | "activity") => void }) {
  const swipe = useSwipeableTabs({
    values: ["details", "activity"],
    activeValue: tab,
    onValueChange: setTab,
  });

  return <section {...swipe.bind}>...</section>;
}

Left swipes move forward, right swipes move backward, and interactive controls such as inputs, buttons, media, tablists, maps, iframes, and canvases are ignored by default.

Overlay back layers

import {
  MobileBackProvider,
  useMobileBackController,
  useMobileBackLayer,
} from "@splitin/react-mobile-interactions";

function Sheet({ open, close }: { open: boolean; close: () => void }) {
  useMobileBackLayer({
    id: "sheet",
    priority: 20,
    enabled: open,
    onBack: () => {
      close();
      return true;
    },
  });

  return open ? <div role="dialog">...</div> : null;
}

function BackButton() {
  const controller = useMobileBackController();
  return <button onClick={() => controller.triggerBack()}>Back</button>;
}

export function App() {
  return (
    <MobileBackProvider>
      <BackButton />
      <Sheet open close={() => undefined} />
    </MobileBackProvider>
  );
}

Layers register by id; the highest enabled priority wins. If a layer returns false from onBack, the controller continues to the next enabled layer.

Edge-swipe back

MobileEdgeBackHandler is router-agnostic. Wire the back behavior in user-land:

import { MobileEdgeBackHandler } from "@splitin/react-mobile-interactions";
import { useNavigate } from "react-router-dom";

function RouterBackGesture() {
  const navigate = useNavigate();

  return (
    <MobileEdgeBackHandler
      onBack={() => navigate(-1)}
      canStart={() => window.history.length > 1}
    />
  );
}

The handler listens for left-edge touch swipes, prevents native horizontal scroll when the gesture clearly becomes a back swipe, triggers haptics when available, and calls onBack only after a committed right swipe.

Route transition

import { MobileRouteTransition } from "@splitin/react-mobile-interactions";

export function MobilePage() {
  return (
    <MobileRouteTransition transitionKey="settings" direction="up">
      <main>...</main>
    </MobileRouteTransition>
  );
}

The default transition is a bottom sheet-up motion using nativeSprings.smooth. Set active={false} to render children directly.

Motion presets

import {
  nativeDialogVariants,
  nativeOverlayVariants,
  nativeSheetVariants,
  nativeSprings,
  shouldAnimate,
} from "@splitin/react-mobile-interactions";

shouldAnimate() reads prefers-reduced-motion at runtime. Components should call it when deciding whether to apply motion-sensitive transforms.

Careers

This folder is product-tech an individual contributor owns end to end. SplitIn engineering: Tech 51%. Business 50. We invest 45% as R&D back to the open-source tools SplitIn uses. MVP first, then merge with tests, trust-me-bro benchmarks, and live user tests. We build fast and then refine — every contributor brings an acquaintance after building the building blocks of the architecture. Every project would be allotted funds. Full mission and stack: splitin.net/tech-stack. Hub: open-internal-tools.

Own this package end to end — or explore SplitIn tech careers — at https://www.splitin.net/careers-requests.

License

MIT. Free to use in personal, open-source, and commercial applications. See LICENSE. Program rules: CONTRIBUTING.md.

SplitIn Dev tools integration

Hosted route: https://www.splitin.net/dev-tools/mobile-interactions (deployment qualification tracked by the host application). Build with Node 24, npm ci, npm run build, then npm test. Consumers install reviewed versioned tarballs; no sibling-source imports are required.

The hosted playground is isolated from customer verification, onboarding and payment eligibility. Public demonstrations keep state in memory and suppress recording. Provider credentials and launch secrets must never be persisted by a browser client. Test keyboard controls, 320/390/768px layouts and reduced motion as well as physical iOS Safari and Android Chrome.

Contained playgrounds (0.2)

MobileEdgeBackHandler accepts an optional target: HTMLElement. Edge coordinates are measured against that element and listeners are removed on target changes/unmount. Omit target to preserve document-wide behavior. Set hapticPattern={false} to disable optional vibration. useSwipeIntent supports mouse and pen and suppresses duplicate touch streams when pointer events are present. Use a local MobileBackProvider to keep demo navigation separate from browser history.