Swipe Actions

new

A list row that slides sideways to reveal actions, the way Mail does on iOS.

Demo
  • Ada Lovelace

    Notes on the engine

  • Grace Hopper

    Q4 roadmap review

  • Alan Turing

    Lunch on Friday?

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.

State
Open: closed

API Reference

Every part accepts class, merged over its base classes.

Data attributes

data-slotAttributesDescription
swipe-root—The list whose rows close one another.
swipe-itemdata-state, data-disabled, data-draggingA row. data-state is closed, start or end.
swipe-actionsdata-side, data-armedA strip of actions. data-armed is set while a full swipe is armed on its side.
swipe-actiondata-color, data-armedAn 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-contentdata-draggingThe 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.

KeyAction
ArrowLeftMoves the content left, opening the strip on the right or closing the one on the left.
ArrowRightMoves the content right, opening the strip on the left or closing the one on the right.
EscapeCloses the open row.

Changelog

  1. registry 0.22.0

    a435c72 — SwipeItem takes a dir prop and renders its direction (the prop, else ConfigProvider) as the row's dir, so the drag, the arrow keys and the strips' placement agree: before, in <html dir="rtl"> without a ConfigProvider, a drag revealed the empty side and the open strip sat outside the row. Such an app now gets left-to-right rows (strips do not swap); set dir="rtl" on the row or wrap the app in ConfigProvider dir="rtl".

  2. core 0.16.0

    129bc1d — SwipeActions: when an action runs from the keyboard or Escape closes the row while focus is in a strip, focus goes back to the element last focused in the row's content (or its first focusable element) instead of dropping to <body> as the strip turns inert.

    8329332 — SwipeActions: an arrow key that a widget inside the row already handled (a ToggleGroup or other roving-focus group calls preventDefault) no longer opens or closes the row.

    a435c72 — SwipeItem takes a dir prop and renders its direction (the prop, else ConfigProvider) as the row's dir, so the drag, the arrow keys and the strips' placement agree: before, in <html dir="rtl"> without a ConfigProvider, a drag revealed the empty side and the open strip sat outside the row. Such an app now gets left-to-right rows (strips do not swap); set dir="rtl" on the row or wrap the app in ConfigProvider dir="rtl".

    1960479 — A SwipeItem rendered open on the server (v-model:state restored to start or end) no longer crashes the render by adding its outside-press and Escape listeners to a document that does not exist there; the hydrated row adds them on the client.

  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. core 0.13.0

    6fb58da — Nested drags no longer start together: the innermost useDrag that starts takes the gesture, and an outer one gets it only when the inner one refuses it. A closed SwipeActions row no longer moves towards a side without actions, so that swipe reaches what is around the row. scrollBlocksDrag reads a right-to-left scroller from its start on the right.

  5. registry 0.10.0

    7e11882 — New SwipeActions item: the core swipe parts with tone-coloured actions (color, icon over label) and an opaque content layer. New drag lib item re-exporting core's useDrag, with a docs page.

  6. core 0.9.0

    7e11882 — New @kappa-ui/core/swipe-actions: SwipeRoot, SwipeItem, SwipeActions, SwipeAction, SwipeActionContent and SwipeContent, a row that slides sideways on useDrag to reveal a strip of actions on its start or end side and holds open on it, with a velocity-projected threshold, an optional full swipe that clicks the outermost action, one open row per SwipeRoot, v-model:state, outside-press, Escape and scroll dismissal, arrow keys and inert closed strips. tailwind.css adds the swipe-item utility that animates them.