Skip to content

docs: Documentation of some new props and features #356

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MatiPl01 merged 2 commits into from
Apr 17, 2025
Merged

docs: Documentation of some new props and features #356

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
52228af
Add documentation of some missing props and proper docs for new callb…
MatiPl01 Apr 17, 2025
a770b29
Some progress
MatiPl01 Apr 17, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
128 changes: 99 additions & 29 deletions packages/docs/docs/flex/props.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ 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:
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`
Expand Down Expand Up @@ -268,7 +268,7 @@ This may sometimes cause **performance issues** as it requires layout recalculat

---

## Item Drag Settings
## Item Drag

### overDrag

Expand Down Expand Up @@ -325,6 +325,42 @@ The maximum distance (in pixels) the finger can move from the touch start positi

---

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

<details>
<summary>Type definitions</summary>

```tsx
type SortableFlexStrategy = 'insert' | SortableFlexStrategyFactory;
```

{/* TODO: Add link to docs page explaining how to use SortableFlexStrategyFactory */}

</details>

### 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).
Expand Down Expand Up @@ -536,11 +572,17 @@ Component to use as the drop indicator. It gives a **full control** over the dro

```tsx
type DropIndicatorComponentProps = {
activationProgress: SharedValue<number>;
touchedItemKey: SharedValue<null | string>;
/** 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;
};
```
Expand All @@ -553,13 +595,9 @@ type DropIndicatorComponentProps = {

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 Warning (Web)

There are some **differences** in the **layout animations** implementation on **Web**:
Expand Down Expand Up @@ -676,6 +714,41 @@ import reorderVideo from '@site/static/video/flex-layout-transition-mode-reorder

## Callbacks

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

```ts
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:
```ts
const onDragStart = useCallback((params: DragStartParams) => {
// Your code here
}, []);
```

:::info
For more information about worklets refer to the [Reanimated documentation](https://docs.swmansion.com/react-native-reanimated/docs/guides/worklets/).
:::

### onDragStart

Called when the drag gesture starts.
Expand Down Expand Up @@ -753,6 +826,12 @@ type OrderChangeParams = {

</details>

:::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
Expand Down Expand Up @@ -782,27 +861,6 @@ type DragMoveParams = {

## Other Settings

### strategy

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

| type | default | required |
| ---------------------- | -------- | -------- |
| `SortableFlexStrategy` | 'insert' | NO |

<details>
<summary>Type definitions</summary>

```tsx
type SortableFlexStrategy = 'insert' | SortableFlexStrategyFactory;
```

{/* TODO: Add link to docs page explaining how to use SortableFlexStrategyFactory */}

</details>

---

### customHandle

Controls whether drag gestures should be restricted to a custom handle component.
Expand Down Expand Up @@ -837,10 +895,22 @@ You can also use any other haptics library but you will have to trigger haptics

---

### 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 |
Loading
Loading