Swipe actions

The user drags a row sideways. The row follows the finger and uncovers buttons underneath: archive, flag, mark as read. Released far enough, it stays open on the buttons; otherwise it closes.

Drag a row left for Flag and Archive, or right for Read. Try a short, fast flick: speed counts as much as distance. Tap anywhere else to close the open row.

The same row, frame by frame:

When to use it

• Lists where the user triages many items in a row: mail, notifications, tasks, conversations.
• Two or three frequent actions per row, at most on each side.

Swipe actions are invisible until someone tries. Keep every action reachable another way: a long press menu, the detail screen, or selection mode. Don’t use them on rows that already react to a horizontal gesture (a carousel, a slider), or in a screen that is itself swiped between tabs.

How it works

translateX is how far the row is from its rest position: negative to reveal the trailing actions, positive for the leading ones.

While dragging

Past the actions’ width w, each point counts less:

x = w + (over * resistance) / (over + resistance); // resistance: 60pt

On release

The row opens or closes from velocity first, then position:

The snap is a spring that starts from the release velocity, so a flick carries on smoothly instead of restarting.

Once open

• A tap on the row, on another row or on the screen closes it without triggering anything else.
• A tap on an action runs it and closes the row. If the action removes the row (archive, delete), the row slides out and the list closes the gap.
• A scroll of the list closes it.

Full swipe

A side can trigger its outermost action with a long swipe, without stopping on the buttons. It suits the one action the user repeats most, often Archive or Delete.

Swipe a row a little, then all the way. What happens after the row leaves, with the snackbar and Undo, is described in undoable action.

progress is |translateX| / rowWidth. Two thresholds split the swipe:

Crossing back under 55% before releasing disarms it: the user can change their mind until the last moment.

Only use a full swipe for an action that can be undone. Deleting something that can’t be restored (a folder with its content, an account) needs a Dialog first.

Implementation

Axiom implements it with one hook, useSwipeActions, and a SwipeableRow that renders the actions behind any Item.

In a screen

<SwipeableList>
	<FlatList
		data={mails}
		renderItem={({ item }) => (
			<SwipeableRow
				leading={[
					{
						key: "read",
						icon: "mail",
						label: "Read",
						color: "info",
						onPress: () => toggleRead(item),
					},
				]}
				trailing={[
					{
						key: "flag",
						icon: "flag",
						label: "Flag",
						color: "warning",
						onPress: () => flag(item),
					},
					{
						key: "archive",
						icon: "archive",
						label: "Archive",
						fullSwipe: true,
						onPress: () => archive(item),
					},
				]}
			>
				<Item onPress={() => open(item)}>…</Item>
			</SwipeableRow>
		)}
	/>
</SwipeableList>

Options and return value are documented in useSwipeActions.

Accessibility

• Expose each action as an accessibilityActions entry on the row: VoiceOver lists them in the rotor, TalkBack in its actions menu. Screen reader users never swipe rows.
• Action buttons are hidden from screen readers while the row is closed, and focusable when it’s open.
• Colors aren’t enough: each action has an icon and a label. The haptic isn’t the only armed signal: the button changes shape too.
• With Reduce Motion on, the snap is a short timing instead of a spring, and a removed row disappears without sliding.

Related

• Undoable action
• Long press
• useSwipeActions
• Item