Swipe Views

new

Pages that follow the finger, the way native apps page between tabs. One page sits in the frame, and a release settles on the nearest one with the speed of the swipe.

Demo
Ada Lovelace

The engine notes are ready

Grace Hopper

Found the bug, literally

Alan Turing

Lunch on Friday?

Katherine Johnson

Trajectory checks out

Linus Torvalds

Patch looks fine, merging

Margaret Hamilton

Priority display works

Dennis Ritchie

Sent you the pointer tips

Barbara Liskov

About that substitution

Design crit

Mia: new icons are up

Release crew

Version PR is green

Book club

Next: The Soul of a New Machine

Climbing

Saturday at nine?

Family

Photos from the weekend

Neighbours

Parcel left at number 4

Vue News

Vapor mode, a first look

Tailwind

A new release is out

Frontend Weekly

Issue 412

CSS Tricks

Scroll-driven animations in practice

Open Source Daily

Five tools worth a star

Installation

Usage

<script setup lang="ts">
import { ref } from 'vue'

import { SwipeView, SwipeViews } from '@/components/ui/swipe-views'

const page = ref('inbox')
</script>

<template>
  <SwipeViews v-model="page" class="h-80">
    <SwipeView value="inbox">…</SwipeView>
    <SwipeView value="sent">…</SwipeView>
    <SwipeView value="drafts">…</SwipeView>
  </SwipeViews>
</template>

v-model holds the value of the page in the frame, a string or a number. Drag a page and it follows the finger. Let go and it settles on the nearest page, or on the next one after a quick flick, so a short fast swipe pages as surely as a long slow one. A finger can catch a page mid-way and drag on from where it is. Mouse, pen and touch all drag; on a touch screen a vertical drag still scrolls. Setting the model from code moves the page with the same transition.

Every page stays mounted. Pages out of the frame are inert, out of the tab order and the accessibility tree until a swipe brings them in. Content that should render late can wait for the active slot prop of SwipeView. Each SwipeView must be a direct child of SwipeViews.

Server-rendered HTML already shows the page in v-model: it is active, the others are inert, and every page sits where it will be once the browser takes over.

Pages lie in a row, and the frame is as tall as the tallest page. With the window as the scroller the pages would share one scroll position, so give the frame a height and each page its own Scroll Area, as the demo does.

Swipe Views is not a carousel: there is no loop, no autoplay, and one page in the frame. For those, use Embla or CSS scroll snap.

Swipe Views runs on Swipe Snap, which you can use on its own for anything else that snaps between points, such as a sheet with a few heights.

Examples

With Tabs

Tabs and Swipe Views share one v-model. Wrap each SwipeView in Reka's TabsContent with force-mount and as-child: the page becomes the tab panel, with role="tabpanel" and aria-labelledby, and stays mounted for the swipe. The demo at the top is built this way.

<script setup lang="ts">
import { TabsContent } from 'reka-ui'
</script>

<template>
  <Tabs v-model="tab">
    <TabsList variant="line">
      <TabsTrigger value="chats">Chats</TabsTrigger>
      <TabsTrigger value="groups">Groups</TabsTrigger>
    </TabsList>
    <SwipeViews v-model="tab" class="h-72">
      <TabsContent value="chats" force-mount as-child>
        <SwipeView value="chats">…</SwipeView>
      </TabsContent>
      <TabsContent value="groups" force-mount as-child>
        <SwipeView value="groups">…</SwipeView>
      </TabsContent>
    </SwipeViews>
  </Tabs>
</template>

Onboarding

Number values pair with Page Indicator, which counts pages from 1.

Onboarding

Welcome

Everything you save lands in one place, on every device.

Find your way

Swipe between your lists, or pick one from the tabs.

Ready to go

Start with an empty list or import the one you have.

Vertical

orientation="vertical" pages up and down and leaves a sideways drag to the page. Give the frame a height.

Vertical

Morning run

@ana

Sourdough, day three

@leo

Rooftop garden

@mia

Night ferry

@sam

Fling

A swipe moves one page at most. With :sequential="false" a hard flick runs to the first or the last page, and a slower drag settles on whichever page is nearest.

Fling
1
2
3
4
5
6
7
8
9
10

Frame 1 of 10

Layouts and effects

Swipe Views moves nothing itself. It writes CSS variables, and the classes on the pages turn them into motion, so anything that reads them follows the finger and settles with the transition, with no script per frame.

Pages lie in a row by default: each one translates by --swipe-snap-offset. With layout="stack" they lie on top of each other instead, each one sliding in over the one before it and staying put once the next one covers it, the way a navigation stack does. Give a stacked frame a height: its pages are positioned absolutely.

Sidebars

kappa-ui

general
Mi
Mia

The avatars stay where they are

Le
Leo

Swipe right for the server names

An
Ana

And the arrow brings the channels back

The example above is laid out the way Discord does it on a phone. The server avatars are not a page: they stay at the start and the channel list sits beside them. A swipe towards the end slides the channel list away and fades the server names in beside the avatars; a swipe the other way, or a tap on a channel, brings the conversation over everything:

<SwipeViews v-model="view" layout="stack" :rubberband="false" class="h-96">
  <ul class="absolute inset-y-0 start-0 w-16">…</ul>
  <SwipeView value="servers" class="start-16 w-[calc(100%-4rem)] opacity-[clamp(0,1+var(--swipe-view-position),1)]">
    …
  </SwipeView>
  <SwipeView value="channels" class="pointer-events-none ps-16">
    <div class="pointer-events-auto h-full">…</div>
  </SwipeView>
  <SwipeView value="chat">…</SwipeView>
</SwipeViews>

A page's size along the axis is the distance to the next page. The server names are 4rem narrower than the frame, which is exactly how far the channel list travels to clear them. The channel list's page spans the whole frame so that the next step is the conversation's width, and its first 4rem lets taps through to the avatars. The last page aligns to the end of the frame, so a narrow last page leaves the one before it peeking in from the other side.

At the first and the last page a drag stretches past the edge and springs back. :rubberband="false" stops it there instead, as the example does, so the conversation never pulls away from the channel list beneath it.

A page out of the frame is inert, so a tap on a page peeking in reaches whatever lies beneath it. To go back on a tap, put a button over the peek.

For a motion of your own, replace a page's translate-* with a class that reads the variables. --swipe-view-offset is where the page is from the start of the frame, so translate-x-[calc(var(--swipe-view-offset)*0.3)] makes a stacked page trail behind at 0.3 of the speed. --swipe-view-position is -1 for the page just behind, 0 for the one in the frame and 1 for the one ahead, fractional in between, so opacity-[calc(1-0.5*abs(var(--swipe-view-position)))] fades the neighbours.

VariableDefaultDescription
--swipe-snap-offset0pxOn the frame and every page, how far the pages have moved, in px. Negative going forwards, mirrored in right-to-left.
--swipe-snap-position0On the frame and every page, the index of the page in the frame, fractional while moving.
--swipe-view-index0On a page, its index.
--swipe-view-start0pxOn a page, where it starts along the row, in px; mirrored in right-to-left.
--swipe-view-position0On a page, its index minus the position, -1 behind, 0 in the frame, 1 ahead.
--swipe-view-offset0pxOn a page, where it is from the start of the frame, in px. 0 in the frame, positive ahead, mirrored in right-to-left.
--swipe-view-stack0pxOn a page, the offset a stacked page translates by. It stops at 0, so a page covered by the next one stays put.
--swipe-snap-durationvar(--transition-duration-medium-4)How long a page takes to settle. Set it with a class on the frame or an ancestor.

The variables stop at the page, so the rest of the page does not restyle on every frame. An element inside a page that needs one takes it with [--swipe-snap-offset:inherit].

Until the frame has measured its pages, which covers server-rendered HTML, each page carries its own --swipe-snap-offset and --swipe-snap-position, and the lengths are percentages of the page's own size: a page that spans the frame lands exactly where it will be measured to.

Swipe areas

A page with sideways gestures of its own competes with the swipe. Swipe Actions rows work inside a page as they are: a drag on a row moves the row, and a drag towards a side the row has no actions on moves the page. For anything else, such as a map or a slider, put data-no-drag on it.

When a page is made entirely of such rows, set swipe-area-only. The pages then move only from a SwipeViewsSwipeArea, a strip along an edge, the way iOS goes back from the edge of the screen. side="start" leads back to the previous page and side="end" on to the next; a strip with no page on its side is off and lets taps through.

Swipe area

Inbox

  • Notes on the engine
  • Q4 roadmap review
  • Lunch on Friday?

Updates

  • Your build passed
  • New sign-in on Linux
  • Invoice for October

Social

  • Mia mentioned you
  • Leo shared an album
  • 3 new followers

A strip lies over the content, so taps on its 20px land on the strip and not on what is beneath. In Safari on iOS the start edge also belongs to the browser's back swipe.

API Reference

Every part accepts class, merged over its base classes.

Data attributes

data-slotAttributesDescription
swipe-viewsdata-orientation, data-layout, data-disabled, data-dragging, data-settlingThe frame. data-dragging is set while a finger moves the pages, data-settling while they settle after it.
swipe-viewdata-state, data-orientationA page. data-state is active for the page in the frame and inactive otherwise.
swipe-views-swipe-areadata-side, data-orientation, data-disabledA strip that starts a swipe. data-disabled is set when there is no page on its side.

Accessibility

Pages out of the frame are inert and become reachable as soon as a swipe brings them on screen. When the page holding focus leaves the frame, focus moves to the new page itself, which shows the inset focus ring only when a key started the change. Swipe Views has no keyboard of its own: a swipe is hard to discover and impossible without a pointer, so drive the model from controls too, such as Tabs, Page Indicator or buttons. With Tabs, the TabsContent pattern above gives each page the tab panel's semantics.

Changelog

  1. registry 0.22.0

    85b907b — A SwipeView page that receives focus (when the page holding it leaves the frame, or a Tabs panel reached with Tab) drops the browser's default outline: it shows the kit's inset focus ring after a keyboard action and nothing after a swipe, a tap or a click.

  2. core 0.16.0

    76d453f — A disabled SwipeViews marks its swipe areas data-disabled, so the registry's strips stop catching taps over the page's edge; the root context gains disabled.

    895afdc — SwipeViews: when the page holding focus turns inert after a page change (a button in it that moves to the next page, say), focus moves to the new page itself instead of dropping to <body>. The page gets tabindex="-1" if it has none, and nothing inside it is focused, so no virtual keyboard opens after a swipe.

    50250ec — SwipeViews renders its state on the server: pages register during setup, so the server HTML marks the page in v-model active and the others inert, and each page places itself by index (in percent of its own size) until the root has measured the pages in the browser, so the first paint shows the model's page instead of the first one, or the last one in the stack layout. Hydration matches the server HTML. --swipe-snap-offset, --swipe-view-offset and --swipe-view-stack are registered as <length-percentage>; the root context gains resolved, measured and resort, and a registered page's element is set once it mounts.

  3. core 0.14.0

    6887534 — A finger drag no longer freezes when a second finger touches the screen: useDrag keeps following the first finger and releases when it lifts, so SwipeViews, useSwipeSnap, Drawer and SwipeActions settle instead of staying stuck mid-drag. A second finger that lands before the drag starts still keeps it from starting. A pen or mouse pressed during a finger drag, or a finger during a pen or mouse drag, no longer starts a second drag on top of the first.

  4. registry 0.17.0

    6c50288 — New SwipeViews: pages that follow the finger, the way native apps page between tabs. It holds the page in the frame in v-model, pairs with Tabs on the same model, and lays its SwipeViews out in a row that a swipe or a flick moves along. layout="stack" lays the pages on top of each other, each sliding in over the one before it, as in a navigation stack. The frame and every page carry CSS variables for layouts and effects of your own. SwipeViewsSwipeArea adds a strip at an edge, and swipe-area-only makes it the only way to swipe. The mechanism underneath comes as its own item, swipe-snap, with useSwipeSnap for sheets, galleries and pagers of your own.

  5. core 0.13.0

    908bb3b — New @kappa-ui/core/swipe-views: SwipeViewsRoot, SwipeView and SwipeViewsSwipeArea, headless pages that follow the finger. The root measures its pages, binds the page in the frame with v-model and writes --swipe-snap-offset and --swipe-snap-position; every page gets --swipe-view-index, --swipe-view-start, data-state, and inert while out of the frame, and the swipe-view utility derives --swipe-view-offset and --swipe-view-stack from them. layout (row or stack) is carried as data-layout, and the root sets dir. A swipe area is a strip that starts a swipe towards the page on its side; swipeAreaOnly makes it the only way to swipe.