Props
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.
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' | NO | 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 |
---|---|---|
number | 'fill' | NO | NO |
width
Width of the flex container. If not specified, the width will be determined by the content.
type | default | required |
---|---|---|
number | 'fill' | 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 |
animateHeight
Whether the height of the flex component should be animated when the items are reordered.
type | default | required |
---|---|---|
boolean | false | NO |
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.
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 |
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.
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;
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 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 |
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 | {} | NO |
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 = {
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.
- 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
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 reorderingitemEntering
anditemExiting
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 | 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 | 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 |
*Library default itemsLayout
implementation for native platforms
**No default value on Web
Type definitions
type LayoutTransition =
| BaseAnimationBuilder
| LayoutAnimationFunction
| typeof BaseAnimationBuilder;
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 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.
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 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
};
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>;
};
Other Settings
strategy
Controls how items are reordered while the active item is being dragged around.
type | default | required |
---|---|---|
SortableFlexStrategy | 'insert' | NO |
Type definitions
type SortableFlexStrategy = 'insert' | SortableFlexStrategyFactory;
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.
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 |
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.
type | default | required |
---|---|---|
boolean | false | NO |