Skip to main content

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.

import { SortableHandle, SortableList } from 'patine-ui';
Loading…
<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>
  )}
/>

Try the props​

Props
activation
<SortableList
data={items}
onReorder={setItems}
keyExtractor={(item) => item}
renderItem={renderRow}
/>

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.

Loading…
<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.

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

PropTypeDefaultDescription
dataT[]—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.
disabledbooleanfalseTurns reordering off.
onDragStart(index: number) => void—A row lifts.
labelsPartial<SortableLabels>EnglishmoveUp, moveDown, moved (with {position} and {count}), keyboardHint.
theme / designprovider's

SortableHandle​

PropTypeDefaultDescription
accessibilityLabelstring'Drag to reorder'
styleStyleProp<ViewStyle>—At least 44 × 44.
theme / designthe 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.