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:

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

Base

children

Children components to render within the flex container.

typedefaultrequired
ReactNodeNONO

sortEnabled

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

typedefaultrequired
Animatable<boolean>trueNO

Flex Layout

alignContent

Controls how item groups are aligned along the cross axis.

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

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

typedefaultrequired
'flex-start' | 'flex-end' | 'center' | 'baseline'NONO

flexDirection

Controls the direction of items in the flex container.

typedefaultrequired
'row' | 'column' | 'row-reverse' | 'column-reverse''row'NO

flexWrap

Controls whether items should wrap or not.

typedefaultrequired
'nowrap' | 'wrap' | 'wrap-reverse''wrap'NO

gap

Gap between items in the flex container.

typedefaultrequired
number0NO

rowGap

Gap between rows in the flex container.

typedefaultrequired
number0NO

columnGap

Gap between columns in the flex container.

typedefaultrequired
number0NO

height

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

typedefaultrequired
number | 'fill'NONO

width

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

typedefaultrequired
number | 'fill'NONO

minHeight

Minimum height of the flex container.

typedefaultrequired
numberNONO

minWidth

Minimum width of the flex container.

typedefaultrequired
numberNONO

maxHeight

Maximum height of the flex container.

typedefaultrequired
numberNONO

maxWidth

Maximum width of the flex container.

typedefaultrequired
numberNONO

padding

Padding of the flex container.

typedefaultrequired
number0NO

paddingTop

Top padding of the flex container.

typedefaultrequired
number0NO

paddingRight

Right padding of the flex container.

typedefaultrequired
number0NO

paddingLeft

Left padding of the flex container.

typedefaultrequired
number0NO

paddingBottom

Bottom padding of the flex container.

typedefaultrequired
number0NO

paddingVertical

Vertical padding of the flex container.

typedefaultrequired
number0NO

paddingHorizontal

Horizontal padding of the flex container.

typedefaultrequired
number0NO

animateHeight

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

typedefaultrequired
booleanfalseNO
warning

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


Item Drag Settings

overDrag

Whether the active item position should be clamped to the flex boundaries or dragging outside of the flex component 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

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

Shadow opacity of the active item.

typedefaultrequired
Animatable<number>0.2NO

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

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

typedefaultrequired
Animatable<[number, number] | number>75NO

autoScrollSpeed

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

typedefaultrequired
Animatable<number>1NO

autoScrollEnabled

Controls whether the auto scroll is enabled.

typedefaultrequired
Animatable<boolean>trueNO
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.

typedefaultrequired
booleanfalseNO

dropIndicatorStyle

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

typedefaultrequired
ViewStyle{}NO

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 = {
activationProgress: SharedValue<number>;
touchedItemKey: SharedValue<null | string>;
dropIndex: SharedValue<number>;
dropPosition: SharedValue<Vector>;
orderedItemKeys: SharedValue<Array<string>>;
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.

note
  • 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:

  • 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 flex container after the initial render.

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

typedefaultrequired
LayoutAnimationSortableItemExiting* / 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.

typedefaultrequired
LayoutTransitionLinearTransition* / null**NO

*Library default itemsLayout implementation for 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.

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

onDragStart

Called when the drag gesture starts.

typedefaultrequired
DragStartCallbackNONO
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 the new order of the items.

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

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

Other Settings

strategy

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

typedefaultrequired
SortableFlexStrategy'insert'NO
Type definitions
type SortableFlexStrategy = 'insert' | SortableFlexStrategyFactory;

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

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


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.

typedefaultrequired
booleanfalseNO