# React Native Sortable List (Drag to Reorder)

> A drag-to-reorder list for React Native on iOS, Android and the web with no native code and no Reanimated: long press or a handle to lift, rows that make way, auto-scroll near the edges, keyboard reordering on the web and Move up / Move down screen-reader actions. Replaces react-native-draggable-flatlist.

# SortableList

A list you reorder by dragging. Hold a row to lift it (or press its `SortableHandle`), drag it, and the other rows make way; drag near the top or bottom and the list scrolls. Drop it and `onReorder` gets the new order. Built on `PanResponder` and a `ScrollView`, so it needs no gesture library.

```tsx
import { SortableHandle, SortableList } from 'patine-ui';
```

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { SortableHandle, SortableList, Text } from 'patine-ui';

export default function Example() {
  const [tasks, setTasks] = useState(['Book flights', 'Pack bags', 'Water the plants', 'Lock the door', 'Call a taxi']);
  return (
    <SortableList
      data={tasks}
      keyExtractor={(task) => task}
      getItemLabel={(task) => task}
      onReorder={setTasks}
      style={{ width: 320, height: 280 }}
      renderItem={({ item }) => (
        <View style={{ flexDirection: 'row', alignItems: 'center', paddingStart: 16, minHeight: 52 }}>
          <Text style={{ flex: 1 }}>{item}</Text>
          <SortableHandle />
        </View>
      )}
    />
  );
}
```

## Example: an Up Next queue

A music player's queue: drag a track by its handle to change what plays next. The first row is always the next song, and the total time stays at the bottom.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { SortableHandle, SortableList, Text, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const TRACKS = [
  { id: 'a', title: 'Weird Fishes', artist: 'Radiohead', secs: 318 },
  { id: 'b', title: 'Holocene', artist: 'Bon Iver', secs: 337 },
  { id: 'c', title: 'Motion Sickness', artist: 'Phoebe Bridgers', secs: 230 },
  { id: 'd', title: 'Pink + White', artist: 'Frank Ocean', secs: 184 },
  { id: 'e', title: 'Seventeen', artist: 'Sharon Van Etten', secs: 290 },
];
const time = (s: number) => `${Math.floor(s / 60)}:${String(s % 60).padStart(2, '0')}`;

export default function Example() {
  const [queue, setQueue] = useState(TRACKS);
  return (
    <VStack gap="sm" style={{ width: '100%', maxWidth: 380 }}>
      <Text weight="semibold">Up next</Text>
      <SortableList
        data={queue}
        keyExtractor={(t) => t.id}
        getItemLabel={(t) => `${t.title} by ${t.artist}`}
        onReorder={setQueue}
        activation="handle"
        style={{ height: 300 }}
        renderItem={({ item, index }) => (
          <View style={{ flexDirection: 'row', alignItems: 'center', paddingStart: 12, minHeight: 56, gap: 12 }}>
            <View style={{ width: 20, alignItems: 'center' }}>{index ? <Text size="sm" color="textSecondary">{index + 1}</Text> : <Icon name="play" size="sm" color="primary" />}</View>
            <View style={{ flex: 1 }}>
              <Text weight={index ? 'regular' : 'semibold'}>{item.title}</Text>
              <Text size="sm" color="textSecondary">{item.artist} · {time(item.secs)}</Text>
            </View>
            <SortableHandle />
          </View>
        )}
      />
      <Text size="sm" color="textSecondary">{queue.length} songs · {time(queue.reduce((s, t) => s + t.secs, 0))}</Text>
    </VStack>
  );
}
```

## Handle only

With `activation="handle"`, rows lift only from their `SortableHandle`, so a long press on the row stays free for your own menu, and swiping on the row always scrolls. The handle lifts the row as soon as it's pressed.

```tsx
<SortableList activation="handle" data={rows} keyExtractor={(r) => r.id} onReorder={setRows} renderItem={({ item, isActive }) => (
  <Row title={item.title} highlighted={isActive} trailing={<SortableHandle />} />
)} />
```

## Keyboard and screen readers

- **Web**: Tab to a row, press Space to pick it up, move it with the up and down arrows, and press Space, Enter or Escape to drop it. Each move is announced ("Moved to position 3 of 5").
- **iOS and Android**: each row has Move up and Move down actions (swipe up or down with VoiceOver, or the TalkBack actions menu). A row is read as one element, named by `getItemLabel`.
- The handle is hidden from screen readers, which use the actions instead.

## Designs

The lifted row casts the design's `lg` shadow (`md` on the web) over a solid fill and grows slightly on iOS and brand. `SortableHandle` draws iOS's three-line reorder control, or the six-dot drag indicator in Material, the web and brand.

## Props

### SortableList

SortableList also takes `ScrollView` props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` | `T[]` | — | The items in their order. |
| `keyExtractor` | `(item, index) => string` | — | A stable key per item. |
| `renderItem` | `({ item, index, isActive }) => ReactNode` | — | `isActive` while the row is lifted or picked up with the keyboard. |
| `onReorder` | `(data: T[], move: { from, to }) => void` | — | The new order. Set `data` to it. |
| `activation` | `'longPress' \| 'handle'` | `'longPress'` | What lifts a row. |
| `getItemLabel` | `(item) => string` | — | The row's name for screen readers. |
| `disabled` | `boolean` | `false` | Turns reordering off. |
| `onDragStart` | `(index: number) => void` | — | A row lifts. |
| `labels` | `Partial<SortableLabels>` | English | `moveUp`, `moveDown`, `moved` (with `{position}` and `{count}`), `keyboardHint`. |
| `theme` / `design` | | provider's | |

### SortableHandle

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `accessibilityLabel` | `string` | `'Drag to reorder'` | |
| `style` | `StyleProp<ViewStyle>` | — | At least 44 × 44. |
| `theme` / `design` | | the list's | |

`moveItem(items, from, to)` is exported too, for moving items in your own state.

SortableList renders every row, so it suits lists up to a few hundred rows; for longer ones, paginate.
