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

children

Children components to render within the flex container.

type	default	required
ReactNode	NO	NO

---

sortEnabled

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

type	default	required
Animatable<boolean>	true	NO

---

Flex Layout

alignContent

Controls how item groups are aligned along the cross axis.

type	default	required
'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'	'flex-start'	NO

---

justifyContent

Controls how items are positioned within groups along the main axis.

type	default	required
'flex-start' | 'flex-end' | 'center' | 'space-between' | 'space-around' | 'space-evenly'	'flex-start'	NO

---

alignItems

Controls how items are aligned within the group along the cross axis.

type	default	required
'flex-start' | 'flex-end' | 'center' | 'baseline'	'flex-start'	NO

---

flexDirection

Controls the direction of items in the flex container.

type	default	required
'row' | 'column' | 'row-reverse' | 'column-reverse'	'row'	NO

---

flexWrap

Controls whether items should wrap or not.

type	default	required
'nowrap' | 'wrap' | 'wrap-reverse'	'wrap'	NO

---

gap

Gap between items in the flex container.

type	default	required
number	0	NO

---

rowGap

Gap between rows in the flex container.

type	default	required
number	0	NO

---

columnGap

Gap between columns in the flex container.

type	default	required
number	0	NO

---

height

Height of the flex container. If not specified, the height will be determined by the content.

type	default	required
'fill' | number	NO	NO

---

width

Width of the flex container. If not specified, the width will be determined by the content.

type	default	required
'fill' | number	NO	NO

---

minHeight

Minimum height of the flex container.

type	default	required
number	NO	NO

---

minWidth

Minimum width of the flex container.

type	default	required
number	NO	NO

---

maxHeight

Maximum height of the flex container.

type	default	required
number	NO	NO

---

maxWidth

Maximum width of the flex container.

type	default	required
number	NO	NO

---

padding

Padding of the flex container.

type	default	required
number	0	NO

---

paddingTop

Top padding of the flex container.

type	default	required
number	0	NO

---

paddingRight

Right padding of the flex container.

type	default	required
number	0	NO

---

paddingLeft

Left padding of the flex container.

type	default	required
number	0	NO

---

paddingBottom

Bottom padding of the flex container.

type	default	required
number	0	NO

---

paddingVertical

Vertical padding of the flex container.

type	default	required
number	0	NO

---

paddingHorizontal

Horizontal padding of the flex container.

type	default	required
number	0	NO

---

dimensionsAnimationType

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

type	default	required
'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 flex boundaries or dragging outside of the flex component 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
SortableFlexStrategy	'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

Type definitions

type SortableFlexStrategy = 'insert' | SortableFlexStrategyFactory;

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

iOSWeb

Shadow opacity of the active item.

type	default	required
Animatable<number>	0.2	NO

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.

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 flex component when the active item is dragged close to the edges of this component. 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 flex component 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 flex component 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.

type	default	required
[number, number] | number	75	NO

---

autoScrollDirection

Direction in which auto scrolling should occur.

type	default	required
'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.

type	default	required
[number, number] | number	1000	NO

---

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.

type	default	required
[number, number] | number	50	NO

---

autoScrollExtrapolation

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

type	default	required
Extrapolation	Extrapolation.EXTEND	NO

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.

type	default	required
number	0*	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.

type	default	required
boolean	false*	NO

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

---

autoScrollEnabled

Controls whether the auto scroll is enabled.

type	default	required
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 flex container.

• Item entering animations are not triggered during the initial render of the flex container
• Item exiting animations are not triggered when the entire flex container 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 flex container after the initial render.

type	default	required
LayoutAnimation | null	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 flex container (except when the entire flex container is unmounted).

type	default	required
LayoutAnimation | null	SortableItemExiting* / 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.

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

• 'all' - items positions are animated when new items are added or removed from the flex component 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;
  indexToKey: Array<string>;
  keyToIndex: Record<string, number>;
};

---

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;
};

---

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.

---

onDragEnd

Called when the drag gesture ends. Data passed to the callback is the new order of the items.

type	default	required
SortableFlexDragEndCallback	NO	NO

Type definitions

type SortableFlexDragEndCallback = (params: SortableFlexDragEndParams) => void;

type SortableFlexDragEndParams = {
  key: string;
  fromIndex: number;
  toIndex: number;
  indexToKey: Array<string>;
  keyToIndex: Record<string, number>;
  order: <I>(data: Array<I>) => Array<I>; // returns new array with items in the new order
};

---

onActiveItemDropped

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

type	default	required
ActiveItemDroppedCallback	NO	NO

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.

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

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

---

stackingOrder

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

type	default	required
'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 flex component.

type	default	required
boolean	true	NO

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 flex component are measured in multiple batches and you see the layout being recalculated more than once.

type	default	required
number	0	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