Swipe Views
newPages 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.
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.
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.
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.
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.
kappa-ui
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.
| Variable | Default | Description |
|---|---|---|
| --swipe-snap-offset | 0px | On the frame and every page, how far the pages have moved, in px. Negative going forwards, mirrored in right-to-left. |
| --swipe-snap-position | 0 | On the frame and every page, the index of the page in the frame, fractional while moving. |
| --swipe-view-index | 0 | On a page, its index. |
| --swipe-view-start | 0px | On a page, where it starts along the row, in px; mirrored in right-to-left. |
| --swipe-view-position | 0 | On a page, its index minus the position, -1 behind, 0 in the frame, 1 ahead. |
| --swipe-view-offset | 0px | On 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-stack | 0px | On 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-duration | var(--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.
Inbox
Updates
Social
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.
SwipeViews
| Prop | Default | Type and description |
|---|---|---|
| modelValue | — | SwipeViewsValueThe |
| defaultValue | — | SwipeViewsValueThe page in the frame on mount when there is no |
| orientation | — | SwipeViewsOrientation
|
| layout | — | SwipeViewsLayout
|
| dir | — | DirectionThe reading direction, |
| sequential | — | booleanMove one page per swipe at most. |
| rubberband | — | booleanLet a drag stretch past the first and the last page and spring back. |
| disabled | — | booleanTurn off the drag. The model still moves the pages. |
| swipeAreaOnly | — | booleanStart a swipe only from a |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Event | Payload and description |
|---|---|
| update:modelValue | [value: SwipeViewsValue]Fires when a swipe lands on another page. |
| Slot | Scope and description |
|---|---|
| default | { modelValue: SwipeViewsValue | undefined; dragging: boolean; settling: boolean; }The |
| Member | Type and description |
|---|---|
| position | numberThe index of the page in the frame, fractional while a finger moves the pages, for script that follows the swipe. |
SwipeView
| Prop | Default | Type and description |
|---|---|---|
| value* | — | SwipeViewsValueThe page's value, a string or a number, matched against the model of |
| asChild | — | booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | { active: boolean; }The page's content. Slot props: |
SwipeViewsSwipeArea
| Prop | Default | Type and description |
|---|---|---|
| side* | — | SwipeViewsSide
|
| asChild | — | booleanRender the single child instead of a wrapper and put the swipe behaviour on it. |
| as | — | AsTag | ComponentThe element or component to render. |
| Slot | Scope and description |
|---|---|
| default | {}Content shown inside the strip, such as a grip; empty by default. |
Props
- modelValue
SwipeViewsValueThevalueof the page in the frame, bound withv-model. Setting it moves there with the transition.- defaultValue
SwipeViewsValueThe page in the frame on mount when there is nov-model.- orientation
SwipeViewsOrientationhorizontalpages sideways,verticalup and down.horizontalby default.- layout
SwipeViewsLayoutrowlays the pages side by side and moves them together.stacklays them on top of each other: each one slides in over the one before it and stays put once the next one covers it.rowby default.- dir
DirectionThe reading direction,ltrorrtl, taken fromConfigProviderwhen unset. Inrtlhorizontal pages run from right to left.- sequential
booleanMove one page per swipe at most.trueby default; withfalsea hard flick runs to the first or the last page.- rubberband
booleanLet a drag stretch past the first and the last page and spring back.trueby default; withfalsethe pages stop hard at the edge, and at the neighbouring page whensequential.- disabled
booleanTurn off the drag. The model still moves the pages.- swipeAreaOnly
booleanStart a swipe only from aSwipeViewsSwipeArea, never from the pages.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Emits
- update:modelValue
[value: SwipeViewsValue]Fires when a swipe lands on another page.
Slots
- default
{ modelValue: SwipeViewsValue | undefined; dragging: boolean; settling: boolean; }TheSwipeViews and anySwipeViewsSwipeArea. Slot props:modelValue,draggingandsettling.
Exposed
- position
numberThe index of the page in the frame, fractional while a finger moves the pages, for script that follows the swipe.
Props
- value*
SwipeViewsValueThe page's value, a string or a number, matched against the model ofSwipeViews.- asChild
booleanRender the single child instead of a wrapper, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{ active: boolean; }The page's content. Slot props:active,truewhile the page is the one in the frame.
Props
- side*
SwipeViewsSidestartleads back to the previous page,endon to the next. For horizontal pages it follows the reading direction; for vertical ones it is the top or the bottom.- asChild
booleanRender the single child instead of a wrapper and put the swipe behaviour on it.- as
AsTag | ComponentThe element or component to render.
Slots
- default
{}Content shown inside the strip, such as a grip; empty by default.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| swipe-views | data-orientation, data-layout, data-disabled, data-dragging, data-settling | The frame. data-dragging is set while a finger moves the pages, data-settling while they settle after it. |
| swipe-view | data-state, data-orientation | A page. data-state is active for the page in the frame and inactive otherwise. |
| swipe-views-swipe-area | data-side, data-orientation, data-disabled | A 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.