Props

info

Whenever Animatable<T> is used, it refers to the following type definition:

type Animatable<T> = SharedValue<T> | T;

This means that properties of type Animatable<T> can accept either of the following:

• a Reanimated Shared Value (SharedValue<T>)
• a static value of type T

Base

data

An array (or array-like list) of items to render.

type	default	required
Array<T>	NO	YES

---

renderItem

Takes an item from data and renders it into the grid.

type	default	required
SortableGridRenderItem<T>	NO	YES

Type definitions

type SortableGridRenderItem<T> = (
  info: SortableGridRenderItemInfo<T>
) => JSX.Element;

type SortableGridRenderItemInfo<T> = {
  item: T;
  index: number;
};

---

keyExtractor

Used to extract a unique key for each item. Key is used for the identification of the item when items are reordered.

type	default	required
(item: T) => string	YES*	NO

*Default keyExtractor implementation works as follows:

• If item is an object and has id or key property, the value of that property is returned
• Otherwise, item is stringified and returned (inefficient for large objects, a custom keyExtractor implementation is recommended)

important

If your data items are objects that have neither id nor key properties, it is strongly recommended to provide a custom keyExtractor implementation returning a unique string for each item.

---

sortEnabled

Controls whether the sorting is enabled and the item hold and drag gesture is handled.

type	default	required
Animatable<boolean>	true	NO

---

Grid Layout

columns

Number of columns in the grid.

type	default	required
number	1	NO

---

rowGap

Gap between rows in the grid.

type	default	required
Animatable<number>	0	NO

---

columnGap

Gap between columns in the grid.

type	default	required
Animatable<number>	0	NO

---

animateHeight

Whether the height of the grid should be animated when the items are reordered.

type	default	required
boolean	false	NO

warning

This may sometimes cause performance issues as it requires layout recalculations.

---

Item Drag

overDrag

Whether the active item position should be clamped to the grid boundaries or dragging outside of the grid is allowed.

type	default	required
'both' | 'horizontal' | 'none' | 'vertical'	'both'	NO

• 'both' - allowed in both directions
• 'horizontal' - allowed in horizontal direction
• 'vertical' - allowed in vertical direction
• 'none' - not allowed

---

dragActivationDelay

The delay (in milliseconds) between when an item is initially pressed and when the drag gesture becomes active.

type	default	required
Animatable<number>	200	NO

---

activationAnimationDuration

Duration (in milliseconds) of the animation after the item becomes active (by default, the item is scaled up and snapped to the finger).

type	default	required
Animatable<number>	300	NO

---

dropAnimationDuration

Duration (in milliseconds) of the animation after the item is dropped (the finger is released).

type	default	required
Animatable<number>	300	NO

---

dragActivationFailOffset

The maximum distance (in pixels) the finger can move from the touch start position without cancelling the activation of the drag gesture.

type	default	required
Animatable<number>	5	NO

---

Reordering

strategy

Controls how items are reordered while the active item is being dragged around.

type	default	required
SortableGridStrategy	'insert'	NO

• 'insert' - items are reordered by inserting the active item at the target position and moving all items between the active item and the target position
• 'swap' - items are reordered by swapping the active item with the target item without moving other items

Type definitions

type SortableGridStrategy = 'insert' | 'swap' | SortableGridStrategyFactory;

reorderTriggerOrigin

Determines position of the reordering trigger point. If that point enters the area of a different item than the current one, the reordering will be triggered.

type	default	required
'center' | 'touch'	'center'	NO

• 'center' - reordering will be triggered when the center of the active item enters the area of a different item
• 'touch' - reordering will be triggered when the touch point enters the area of a different item

---

Active Item Decoration

All active item decoration settings are applied when the item becomes active (when drag gesture starts being handled).

activeItemScale

Scale to which the pressed item is scaled when active.

type	default	required
Animatable<number>	1.1	NO

---

activeItemOpacity

Opacity to which the pressed item is animated when active.

type	default	required
Animatable<number>	1	NO

---

activeItemShadowOpacity

Shadow opacity of the active item.

type	default	required
Animatable<number>	0.2	NO

---

inactiveItemOpacity

Opacity to which all items except the pressed one are animated when pressed item becomes active.

type	default	required
Animatable<number>	0.5	NO

---

inactiveItemScale

Scale to which all items except the pressed one are animated when pressed item becomes active.

type	default	required
Animatable<number>	1	NO

---

Active Item Snap

Active item snap settings determine how the active item will be positioned in relation to the finger when the drag gesture starts. They control snapping of the active item to the user's finger.

info

When a custom drag handle component is used, the active item snap is relative to the drag handle and not the item itself.

enableActiveItemSnap

Whether the active item should snap to the finger.

type	default	required
Animatable<boolean>	true	NO

---

snapOffsetX

Horizontal snap offset of the item. When percentage is used, it is relative to the width of the item.

type	default	required
Animatable<Offset>	'50%'	NO

Type definitions

type Offset = `${number}%` | number;

---

snapOffsetY

Vertical snap offset of the item. When percentage is used, it is relative to the height of the item.

type	default	required
Animatable<Offset>	'50%'	NO

Type definitions

type Offset = `${number}%` | number;

tip

You can think of the snap offset as a point positioned relative to the top left corner of the item. The snapOffsetX moves the point to the right and the snapOffsetY moves it down.

---

Auto Scroll

Auto scroll settings control the behavior of the grid when the active item is dragged close to the edges of the grid. They are used to automatically scroll the scrollable container when the active item is close to the edges.

scrollableRef

An AnimatedRef to the scrollable container (e.g. Animated.ScrollView or Animated.FlatList from react-native-reanimated) within which the grid is rendered.

type	default	required
AnimatedRef<any>*	NO	NO**

*This is just a temporary type.

**You need to provide this prop if you want to use auto scroll.

---

autoScrollActivationOffset

Offset from the edge of the grid at which the auto scroll is activated.

You can provide a single number, which will be used for both top and bottom edges or an array of two numbers, first for top edge and second for bottom edge.

type	default	required
Animatable<[number, number] | number>	75	NO

---

autoScrollSpeed

Speed of the auto scroll. Adjust it based on your preferences.

type	default	required
Animatable<number>	1	NO

---

autoScrollEnabled

Controls whether the auto scroll is enabled.

type	default	required
Animatable<boolean>	true	NO

important

Use this prop to disable auto scroll instead of removing the scrollableRef prop. The scrollableRef prop cannot be changed on the fly.

---

Drop Indicator

Drop indicator settings control the visual feedback showing the target position of the active item at which it will be positioned when the drag gesture ends.

showDropIndicator

Controls whether the drop indicator is shown.

type	default	required
boolean	false	NO

---

dropIndicatorStyle

Style of the drop indicator. This is typically used to customize the appearance of the default drop indicator component.

type	default	required
ViewStyle	See below	NO

Default value:

{
  backgroundColor: 'rgba(0, 0, 0, 0.1)',
  borderColor: 'black',
  borderRadius: 10,
  borderStyle: 'dashed',
  borderWidth: 2,
  flex: 1
}

important

Values you provide in the dropIndicatorStyle prop will be merged with the default values.

---

DropIndicatorComponent

Component to use as the drop indicator. It gives a full control over the drop indicator appearance and behavior.

type	default	required
ComponentType<DropIndicatorComponentProps>	YES*	NO

*Default DropIndicatorComponent implementation is a simple View with a dashed border and a semi-transparent background.

Type definitions

type DropIndicatorComponentProps = {
  /** Progress of the active item animation (from 0 to 1) */
  activeAnimationProgress: SharedValue<number>;
  /** Key of the currently dragged item, or null if no item is being dragged */
  activeItemKey: SharedValue<null | string>;
  /** Current index where the dragged item would be dropped */
  dropIndex: SharedValue<number>;
  /** Current position where the item would be dropped */
  dropPosition: SharedValue<Vector>;
  /** Array of item keys in their current order */
  orderedItemKeys: SharedValue<Array<string>>;
  /** Style to be applied to the drop indicator */
  style: ViewStyle;
};

---

Layout Animations

Layout animations control how items animate when their positions change and when they are added or removed from the grid.

• Item entering animations are not triggered during the initial render of the grid
• Item exiting animations are not triggered when the entire grid is unmounted

Warning (Web)

There are some differences in the layout animations implementation on Web:

• itemLayout is ignored since Web implementation doesn't use Reanimated layout transitions for items reordering
• itemEntering and itemExiting don't have default values due to the inconsistent behavior, but you can provide your own animations that will be used instead

itemEntering

Layout animation to use when an item is added to the grid after the initial render of the grid.

type	default	required
LayoutAnimation	SortableItemEntering* / null**	NO

*Library default itemEntering implementation for native platforms

**No default value on Web

Type definitions

type LayoutAnimation =
  | BaseAnimationBuilder
  | EntryExitAnimationFunction
  | typeof BaseAnimationBuilder;

---

itemExiting

Layout animation to use when an item is removed from the grid (except when the entire grid is unmounted).

type	default	required
LayoutAnimation	SortableItemExiting* / null**	NO

*Library default itemExiting implementation for native platforms

**No default value on Web

Type definitions

type LayoutAnimation =
  | BaseAnimationBuilder
  | EntryExitAnimationFunction
  | typeof BaseAnimationBuilder;

---

itemsLayout

Layout transition to use when items are reordered.

type	default	required
LayoutTransition	LinearTransition* / null**	NO

*Used as a default value on native platforms

**No default value on Web

Type definitions

type LayoutTransition =
  | BaseAnimationBuilder
  | LayoutAnimationFunction
  | typeof BaseAnimationBuilder;

Warning (Web)

This prop is not supported on Web.

---

itemsLayoutTransitionMode

Controls when items positions are animated.

type	default	required
'all' | 'reorder'	'all'	NO

• 'all' - items positions are animated when new items are added or removed from the grid and when items are reordered
• 'reorder' - items positions are animated only when items are reordered

'all'	'reorder'

---

Callbacks

Performance Recommendation

Use worklet functions for callbacks to run directly on the UI thread and avoid thread jumping overhead.

All callbacks accept two types of functions:

1. Worklet Functions (Recommended)

   • To mark a function as worklet, you have to add 'worklet' directive at the start of the function body
   • Run directly on the UI thread
   • More performant
   • Example:

   const onDragStart = useCallback((params: DragStartParams) => {
     'worklet';
     // Your code here
   }, []);

2. Plain JS Functions

   • No special directive needed
   • Runs on the JS thread by using runOnJS
   • Less performant due to jumping between threads
   • Example:

   const onDragStart = useCallback((params: DragStartParams) => {
     // Your code here
   }, []);

info

For more information about worklets refer to the Reanimated documentation.

onDragStart

Called when the drag gesture starts.

type	default	required
DragStartCallback	NO	NO

Type definitions

type DragStartCallback = (params: DragStartParams) => void;

type DragStartParams = {
  key: string;
  fromIndex: number;
};

---

onDragEnd

Called when the drag gesture ends. Data passed to the callback is sorted according to the new order of the items. If the order of items is not changed, the same data array as the one passed to the data prop of the grid is passed in the callback params.

type	default	required
SortableGridDragEndCallback<T>	NO	NO

Type definitions

type SortableGridDragEndCallback<T> = (
  params: SortableGridDragEndParams<T>
) => void;

type SortableGridDragEndParams<T> = {
  key: string;
  fromIndex: number;
  toIndex: number;
  indexToKey: Array<string>;
  keyToIndex: Record<string, number>;
  data: Array<T>;
};

---

onOrderChange

Called when the order of the items changes while dragging.

type	default	required
OrderChangeCallback	NO	NO

Type definitions

type OrderChangeCallback = (params: OrderChangeParams) => void;

type OrderChangeParams = {
  key: string;
  fromIndex: number;
  toIndex: number;
  indexToKey: Array<string>;
  keyToIndex: Record<string, number>;
};

warning

Don't use this callback to update items order in state because it's called frequently during dragging. Use onDragEnd for state updates instead.

---

onDragMove

Called when the drag gesture moves.

type	default	required
DragMoveCallback	NO	NO

Type definitions

type DragMoveCallback = (params: DragMoveParams) => void;

type DragMoveParams = {
  key: string;
  fromIndex: number;
  touchData: TouchData;
};

---

Other Settings

customHandle

Controls whether drag gestures should be restricted to a custom handle component.

type	default	required
boolean	false	NO

When set to true, items can only be dragged using a dedicated handle component.

important

When customHandle is enabled, you must include a Sortable.Handle component within each grid item, otherwise items will not be draggable.

---

hapticsEnabled

Whether haptics are enabled. Vibrations are fired when the pressed item becomes active, the order of items changes or the drag gesture ends and the item is dropped.

type	default	required
boolean	false	NO

---

important

To use built-in haptics, you have to install react-native-haptic-feedback package. See this Getting Started section for more details.

You can also use any other haptics library but you will have to trigger haptics manually when callbacks are called. See the Callbacks section for more details.

---

overflow

Controls if the overflowing content should be clipped or visible. Applies only when no item is active.

type	default	required
'hidden' | 'visible'	'hidden'	NO

---

debug

Enables debug mode, which shows additional views helpful for debugging. This property is intended for the library developers and is not recommended for the library users.

Debug mode has no effect in production builds and can be used to debug the library only in the development environment.

type	default	required
boolean	false	NO