Swipeable Item

When to Use

Use SwipeableItem when a list row has a few quick actions that touch users can reveal by swiping, while keyboard users can reveal the same actions with Arrow keys. Keep an obvious non-swipe path to important actions. Use a Menu when there are many actions or when a hidden swipe gesture would be surprising.

Features

The behavior Atom owns before your product adds appearance.

• Supports start and end action panels.
• Supports pointer dragging and keyboard opening.
• Preserves native vertical panning with an axis-compatible touch policy.
• Supports controlled and uncontrolled open side state.
• Supports left-to-right and right-to-left direction.
• Supports optional full-swipe actions.
• Closes open action panels after action clicks by default.
• Supports asChild and render on every part.

Import

import { SwipeableItem } from "@flowstack-ui/atom";

Anatomy

<SwipeableItem.Root>
  <SwipeableItem.Actions side="start" />
  <SwipeableItem.Content />
  <SwipeableItem.Actions side="end" />
</SwipeableItem.Root>

API Reference

Root

Owns the open side, drag offset, direction, thresholds, and measured action widths shared by Content and Actions.

ARIA: Root adds no role or ARIA attributes.

Content

Renders the focusable row surface that interprets horizontal pointer movement and keyboard commands. It mirrors Root state and remains focusable when read-only. Atom applies touch-action: pan-y so vertical document or scroll-container panning remains native. An authored style.touchAction can override that default deliberately. Arrow-key reveal runs only while Content itself is the keyboard target; interactive descendants retain their own Arrow behavior.

Actions

Groups the controls revealed on one logical side. Closed panels are both aria-hidden and inert, so their controls cannot be reached accidentally.

Advanced parts can use useSwipeableItemContext and its public provider. The exported side, size, offset, clamping, and direction helpers expose Root's direction-aware calculations.

Examples

Two-sided actions

import { SwipeableItem } from "@flowstack-ui/atom";

export default function MessageActions() {
  return (
<SwipeableItem.Root>
  <SwipeableItem.Actions side="start">
    <button type="button">Archive</button>
  </SwipeableItem.Actions>
  <SwipeableItem.Content>Email from Alex</SwipeableItem.Content>
  <SwipeableItem.Actions side="end">
    <button type="button">Delete</button>
  </SwipeableItem.Actions>
</SwipeableItem.Root>
  );
}

Full-swipe action

import { SwipeableItem } from "@flowstack-ui/atom";

export default function FullSwipeAction() {
  return (
<SwipeableItem.Root onFullSwipe={(side) => window.alert(`Full swipe: ${side}`)}>
  <SwipeableItem.Actions side="end">
    <button type="button">Delete</button>
  </SwipeableItem.Actions>
  <SwipeableItem.Content>Message</SwipeableItem.Content>
</SwipeableItem.Root>
  );
}

Accessibility

SwipeableItem provides equivalent pointer and keyboard operation rather than a special WAI-ARIA widget role. Content is keyboard focusable. Arrow keys open, close, and can full-swipe action panels when onFullSwipe is provided. Escape closes the item. Hidden action panels are removed from the accessibility tree and made inert until open.

Swipe must remain an enhancement. Provide an obvious tap/click path to every command, such as a visible overflow-menu trigger or persistent action. Keyboard support alone is not the required single-pointer alternative to dragging.

Changelog

Unreleased

0.24.0

• Added source-led Agent Knowledge for gesture-enhanced row actions, required non-swipe fallbacks, pointer and scroll behavior, keyboard isolation, logical direction, and action accessibility.

0.19.9

• Preserved native vertical panning with an axis-compatible Content touch policy and stopped bubbled Arrow keys from nested controls from revealing action panels.
• Added real-browser and numbered manual evidence for gesture settlement, cancellation, keyboard isolation, logical direction, and scrolling.

0.2.0

• Added closeOnClick to SwipeableItem.Actions, defaulting to closing the open item after an action click.
• Updated keyboard handling so the opposite arrow closes an open side and the same arrow can trigger onFullSwipe.
• Allowed drag travel to full content width even when no full-swipe callback is configured; release still settles using the configured threshold.

0.1.0

• Initial Atom release.