Swipe Actions
newA list row that slides sideways to reveal actions, the way Mail does on iOS.
Installation
Usage
<script setup lang="ts">
import { SwipeAction, SwipeActions, SwipeContent, SwipeItem, SwipeRoot } from '@/components/ui/swipe-actions'
</script>
<template>
<SwipeRoot as="ul">
<SwipeItem as="li">
<SwipeActions side="end" full-swipe>
<SwipeAction color="destructive" @click="remove">Delete</SwipeAction>
</SwipeActions>
<SwipeContent>Grace Hopper</SwipeContent>
</SwipeItem>
</SwipeRoot>
</template>
Drag a row sideways and the strip on that side slides in with it. Released past half the strip, or on a quick flick, the row stays open on the strip; otherwise it springs back. Tap an action to run it and close the row; tap the row, press anywhere else or press Escape to close it. With close-on-scroll, any scroll closes it too. Mouse, pen and touch all drag; on a touch screen a vertical drag still scrolls the list. A closed row does not move towards a side without actions, so that swipe reaches whatever is around the row, such as a side drawer or Swipe Views.
side is start or end in the reading direction, so the strips swap places in right-to-left text. The row takes the direction from its dir prop or Reka's ConfigProvider and renders it as its own dir; <html dir="rtl"> alone is not read, so a right-to-left app wraps itself in ConfigProvider dir="rtl". A row takes up to one strip per side. Actions sit from the content outwards in the order you write them, each as wide as its content, at least 80px.
With full-swipe on a strip, dragging past half the row arms its outermost action: it floods the row and data-armed is set on the strip and the action. Released armed, the action is clicked, so a tap and a full swipe reach the same handler.
Inside a SwipeRoot, opening a row closes the one that was open. The root renders nothing of its own; as="ul" with as="li" on the items makes the list.
Examples
Open state
v-model:state holds closed, start or end, and setting it opens or closes the row. The exposed open(side) and close() do the same.
API Reference
Every part accepts class, merged over its base classes.
SwipeItem
| Prop | Default | Type and description |
|---|---|---|
| threshold | — | numberFraction of a strip's width the release position must pass to open that side. |
| velocityFactor | — | numberSeconds of release velocity added to the release position, so a quick flick opens the row without dragging all the way. |
| fullSwipeThreshold | — | numberFraction of the row's width a drag must pass to arm a side's full swipe. |
| closeOnScroll | — | booleanClose the row on any scroll on the page. |
| disabled | — | booleanTurn off the gesture and the arrow keys. |
| dir | — | DirectionThe reading direction, |
| 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, such as |
| state | — | SwipeStateWhich side is open: |
| Event | Payload and description |
|---|---|
| update:state | [value: SwipeState]Fires when the row opens on a side or closes. |
| Slot | Scope and description |
|---|---|
| default | {}Up to one |
| Member | Type and description |
|---|---|
| open | (side: SwipeSide) => void | undefinedOpens the given side, |
| close | () => void | undefinedCloses the row. |
SwipeActions
| Prop | Default | Type and description |
|---|---|---|
| side* | — | SwipeSideThe side of the row the strip sits on, |
| fullSwipe | — | booleanLet a drag past |
| 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 | {}The |
SwipeAction
| Prop | Default | Type and description |
|---|---|---|
| closeOnClick | true | booleanClose the row once the click handler has run. |
| asChild | — | booleanRender the single child instead of a button, merging this part's attributes and classes onto it. |
| as | — | AsTag | ComponentThe element or component to render. |
| color | "primary" | SwipeActionColor | (string & {})Colour role the action is filled with. Any other name picks up a colour you declare on |
| Slot | Scope and description |
|---|---|
| default | {}The icon and label, stacked. |
SwipeContent
| Prop | Default | Type and description |
|---|---|---|
| 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 | {}The row itself, typically an |
SwipeRoot
| Prop | Default | Type and description |
|---|---|---|
| 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, such as |
| Slot | Scope and description |
|---|---|
| default | {}The |
Props
- threshold
numberFraction of a strip's width the release position must pass to open that side.0.5by default.- velocityFactor
numberSeconds of release velocity added to the release position, so a quick flick opens the row without dragging all the way.0.2by default.- fullSwipeThreshold
numberFraction of the row's width a drag must pass to arm a side's full swipe.0.5by default.- closeOnScroll
booleanClose the row on any scroll on the page.- disabled
booleanTurn off the gesture and the arrow keys.- dir
DirectionThe reading direction,ltrorrtl, taken fromConfigProviderwhen unset and rendered as the row'sdir. Inrtlthe strips swap sides and the drag and the arrow keys mirror.- 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, such asliin a list.- state
SwipeStateWhich side is open:closed,startorend, bound withv-model:state. Setting it opens or closes the row.closedby default.
Emits
- update:state
[value: SwipeState]Fires when the row opens on a side or closes.
Slots
- default
{}Up to oneSwipeActionsper side, and theSwipeContent.
Exposed
- open
(side: SwipeSide) => void | undefinedOpens the given side,startorend.- close
() => void | undefinedCloses the row.
Props
- side*
SwipeSideThe side of the row the strip sits on,startorend, in the reading direction.- fullSwipe
booleanLet a drag pastfullSwipeThresholdrun the outermost action on release, which floods the row while armed.- 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
{}TheSwipeActions, from the one nearest the content outwards.
Props
- closeOnClick
true booleanClose the row once the click handler has run.- asChild
booleanRender the single child instead of a button, merging this part's attributes and classes onto it.- as
AsTag | ComponentThe element or component to render.- color
"primary" SwipeActionColor | (string & {})Colour role the action is filled with. Any other name picks up a colour you declare on[data-slot][data-color="<name>"].
Slots
- default
{}The icon and label, stacked.
Props
- 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
{}The row itself, typically anItem. It needs an opaque background, which the part gives it.
Props
- 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, such asulfor a list.
Slots
- default
{}TheSwipeItems, at any depth. Opening one closes the others.
Data attributes
| data-slot | Attributes | Description |
|---|---|---|
| swipe-root | — | The list whose rows close one another. |
| swipe-item | data-state, data-disabled, data-dragging | A row. data-state is closed, start or end. |
| swipe-actions | data-side, data-armed | A strip of actions. data-armed is set while a full swipe is armed on its side. |
| swipe-action | data-color, data-armed | An action, filled with its colour. data-armed is set on the outermost action while a full swipe is armed. |
| swipe-action-content | — | The visible slice of an action, its icon and label. |
| swipe-content | data-dragging | The layer that moves with the drag. |
Accessibility
Actions are buttons named by their label. A closed strip is inert, so its actions are out of the tab order and the accessibility tree until the row opens. From the row's focused content, the arrow keys open and close the strips. A swipe is hard to discover with a screen reader, so offer the same actions in another place too, such as a menu on the row.
| Key | Action |
|---|---|
| ArrowLeft | Moves the content left, opening the strip on the right or closing the one on the left. |
| ArrowRight | Moves the content right, opening the strip on the left or closing the one on the right. |
| Escape | Closes the open row. |