Skip to main content

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.

typedefaultrequired
Array<T>NOYES

renderItem​

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

typedefaultrequired
SortableGridRenderItem<T>NOYES
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.

typedefaultrequired
(item: T) => stringYES*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.

typedefaultrequired
Animatable<boolean>trueNO

Grid Layout​

columns​

Number of columns in the grid.

typedefaultrequired
number1NO

rows​

Number of rows in the grid.

Setting this prop switches the grid to a horizontal layout, in which items flow from left to right, then top to bottom.

typedefaultrequired
numberNONO*

*Required to create a horizontal grid. Must be used together with rowHeight and cannot be combined with columns.

rowHeight​

Fixed height of each row, in pixels. All rows of a horizontal grid have the same height.

typedefaultrequired
numberNONO*

*Required when rows is set. Has no effect on vertical grids.

rowGap​

Gap between rows in the grid.

typedefaultrequired
Animatable<number>0NO

columnGap​

Gap between columns in the grid.

typedefaultrequired
Animatable<number>0NO

dimensionsAnimationType​

Whether and how to animate container dimensions changes.

typedefaultrequired
'layout' | 'none' | 'worklet''none'NO
  • 'none' - No animation
  • 'layout' - uses Reanimated Layout Animations
  • 'worklet' - uses Reanimated worklet-based animations
info
  • 'layout' mode is more performant than 'worklet' but it doesn't affect surrounding views during the animation (surrounding content updates position immediately).
  • 'worklet' mode affects surrounding views but is less performant as it requires layout recalculations on every frame.

Item Drag​

overDrag​

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

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

typedefaultrequired
Animatable<number>200NO

activationAnimationDuration​

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

typedefaultrequired
Animatable<number>300NO

dropAnimationDuration​

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

typedefaultrequired
Animatable<number>300NO

dragActivationFailOffset​

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

typedefaultrequired
Animatable<number>5NO

Reordering​

strategy​

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

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

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

typedefaultrequired
Animatable<number>1.1NO

activeItemOpacity​

Opacity to which the pressed item is animated when active.

typedefaultrequired
Animatable<number>1NO

activeItemShadowOpacity
iOSWeb
​

Shadow opacity of the active item.

typedefaultrequired
Animatable<number>0.2NO
info

If you want to use shadows on Android, please refer to the Custom Shadow example.

inactiveItemOpacity​

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

typedefaultrequired
Animatable<number>0.5NO

inactiveItemScale​

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

typedefaultrequired
Animatable<number>1NO

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.

typedefaultrequired
Animatable<boolean>trueNO

snapOffsetX​

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

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

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

typedefaultrequired
AnimatedRef<any>*NONO**

*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 edges or an array of two numbers, first for the top/left edge and second for the bottom/right edge.

typedefaultrequired
[number, number] | number75NO

autoScrollDirection​

Direction in which auto scrolling should occur.

typedefaultrequired
'horizontal' | 'vertical''vertical'NO

autoScrollMaxVelocity​

Maximum scroll velocity in pixels per second when the active item is at the edge.

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

typedefaultrequired
[number, number] | number1000NO

autoScrollMaxOverscroll​

Maximum distance the scrollable container can be scrolled beyond its content bounds while auto scrolling.

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

typedefaultrequired
[number, number] | number50NO

autoScrollExtrapolation​

Controls how the scroll velocity behaves beyond the activation offset threshold.

typedefaultrequired
ExtrapolationExtrapolation.EXTENDNO
info

Extrapolation is imported from react-native-reanimated. Use Extrapolation.CLAMP to stop increasing the scroll velocity once the pointer moves past the activation offset.

autoScrollInterval​

Interval between consecutive scrollTo calls, in milliseconds.

typedefaultrequired
number0*NO

*Defaults to 300 on Android with the New Architecture and 0 everywhere else.

animateScrollTo​

Whether scrollTo calls should be animated.

The main purpose of this prop is to ensure that scroll position changes are animated when autoScrollInterval is set to a large value.

typedefaultrequired
booleanfalse*NO

*Defaults to true on Android with the New Architecture and false everywhere else.

autoScrollEnabled​

Controls whether the auto scroll is enabled.

typedefaultrequired
booleantrueNO
important

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

autoAdjustOffsetDuringDrag​

Whether the scroll offset of the scrollable container should be adjusted automatically when items change their size during a drag.

This keeps the content under the finger visually stable when the grid grows or shrinks while an item is being dragged.

typedefaultrequired
booleanfalseNO
info

Takes effect only when the scrollableRef prop is provided.

autoAdjustOffsetResetTimeout​

Timeout in milliseconds to wait for layout updates after the active item is released.

React state updates happen asynchronously after the drag end callback fires. During this period the released item must still be treated as active to prevent content jumps.

typedefaultrequired
number1000NO

autoAdjustOffsetScrollPadding​

Padding used when adjusting the scroll offset after the active item is released, keeping the released item visible with some distance from the container edges.

You can provide a single number, which will be used for both edges or an array of two numbers, first for the top/left edge and second for the bottom/right edge. Pass null to disable scrolling to the released item.

typedefaultrequired
[number, number] | null | number25NO
info

Takes effect only when autoAdjustOffsetDuringDrag is true and the scrollableRef prop is provided.

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.

typedefaultrequired
booleanfalseNO

dropIndicatorStyle​

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

typedefaultrequired
ViewStyleSee belowNO

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.

typedefaultrequired
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:

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

typedefaultrequired
LayoutAnimation | nullSortableItemEntering* / 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).

typedefaultrequired
LayoutAnimation | nullSortableItemExiting* / null**NO

*Library default itemExiting implementation for native platforms

**No default value on Web

Type definitions
type LayoutAnimation =
  | BaseAnimationBuilder
  | EntryExitAnimationFunction
  | typeof BaseAnimationBuilder;

itemsLayoutTransitionMode​

Controls when items positions are animated.

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

typedefaultrequired
DragStartCallbackNONO
Type definitions
type DragStartCallback = (params: DragStartParams) => void;

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

onDragMove​

Called when the drag gesture moves.

typedefaultrequired
DragMoveCallbackNONO
Type definitions
type DragMoveCallback = (params: DragMoveParams) => void;

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

onOrderChange​

Called when the order of the items changes while dragging.

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

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.

typedefaultrequired
SortableGridDragEndCallback<T>NONO
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>;
};

onActiveItemDropped​

Called when the active item is dropped (the animation to the target item position is completed).

typedefaultrequired
ActiveItemDroppedCallbackNONO
Type definitions
type ActiveItemDroppedCallback = (params: ActiveItemDroppedParams) => void;

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

Other Settings​

customHandle​

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

typedefaultrequired
booleanfalseNO

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.

typedefaultrequired
booleanfalseNO
important

To use built-in haptics, install one of react-native-pulsar, expo-haptics or react-native-haptic-feedback. The library auto-detects whichever is available. 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.

typedefaultrequired
'hidden' | 'visible''visible'NO

stackingOrder​

Strategy for setting zIndex of items. This determines which items appear on top when they overlap.

typedefaultrequired
'asc' | 'desc''asc'NO
  • 'asc' - items with higher index have higher zIndex (default). This means items at the end of the list of items are rendered on top of items at the beginning.
  • 'desc' - items with higher index have lower zIndex. This means items at the beginning of the list of items are rendered on top of items at the end.
info

The currently dragged item is always rendered on top of all other items, regardless of this setting.

bringToFrontWhenActive​

Controls whether the zIndex of the sortable container should be raised when a drag starts. This makes the dragged item render above sibling components outside of the grid.

typedefaultrequired
booleantrueNO
info

If dragged items still appear under other components, wrap the surrounding content in a Layer component.

measureDebounceDelay​

Delay in milliseconds between the last item measurement and the measurements commit that triggers the layout calculation.

Increase it if items of your grid are measured in multiple batches and you see the layout being recalculated more than once.

typedefaultrequired
number0NO

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.

typedefaultrequired
booleanfalseNO