Skip to content

Commit 306395e

Browse files
MatiPl01MatiPl01
authored
docs: Sortable.Handle docs with example (#357)
## Description This PR adds missing `Sortable.Handle` component documentation and related example to docs.
1 parent 1e2d11b commit 306395e

5 files changed

Lines changed: 164 additions & 49 deletions

File tree

‎packages/docs/docs/grid/examples/handle.mdx‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
sidebar_position: 6
3+
description: ''
4+
---
5+
6+
# Custom Handle
7+
8+
## Description
9+
10+
The **Custom Handle** example demonstrates how to use a custom item drag handle.
11+
12+
## Usage
13+
14+
### Source Code
15+
16+
```tsx
17+
import { faGripVertical } from '@fortawesome/free-solid-svg-icons';
18+
import { FontAwesomeIcon } from '@fortawesome/react-native-fontawesome';
19+
import { useCallback } from 'react';
20+
import { StyleSheet, Text, View } from 'react-native';
21+
import type { SortableGridRenderItem } from 'react-native-sortables';
22+
import Sortable from 'react-native-sortables';
23+
24+
const DATA = Array.from({ length: 8 }, (_, index) => `Item ${index + 1}`);
25+
26+
export default function PlaygroundExample() {
27+
const renderItem = useCallback<SortableGridRenderItem<string>>(
28+
({ item }) => (
29+
<View style={styles.card}>
30+
<Text style={styles.text}>{item}</Text>
31+
{/* Wraps the handle component (an icon in this case) */}
32+
<Sortable.Handle>
33+
<FontAwesomeIcon color='white' icon={faGripVertical} />
34+
</Sortable.Handle>
35+
</View>
36+
),
37+
[]
38+
);
39+
40+
return (
41+
<View style={styles.container}>
42+
<Sortable.Grid
43+
activeItemScale={1.05}
44+
columns={1}
45+
data={DATA}
46+
overDrag='vertical'
47+
renderItem={renderItem}
48+
rowGap={10}
49+
customHandle // must be set to use a custom handle
50+
/>
51+
</View>
52+
);
53+
}
54+
55+
const styles = StyleSheet.create({
56+
card: {
57+
alignItems: 'center',
58+
backgroundColor: '#36877F',
59+
borderRadius: 12,
60+
flexDirection: 'row',
61+
justifyContent: 'center',
62+
padding: 24
63+
},
64+
container: {
65+
padding: 16
66+
},
67+
text: {
68+
color: 'white',
69+
flex: 1,
70+
fontWeight: 'bold'
71+
}
72+
});
73+
```
74+
75+
## Result
76+
77+
import handleVideo from '@site/static/video/grid-custom-handle.mp4';
78+
79+
<video autoPlay loop muted width='300px' src={handleVideo} />

‎packages/docs/docs/helper-components/handle.mdx‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
---
2+
sidebar_position: 1
3+
description: 'Component that allows to drag an item by a specific area'
4+
---
5+
6+
# Handle
7+
8+
## Overview
9+
10+
The **Handle** component allows you to drag an item by a specific area (part of the item) instead of the whole item.
11+
12+
## Usage
13+
14+
:::info
15+
16+
For the complete usage example, refer to the [Handle](/grid/examples/handle) example.
17+
18+
:::
19+
20+
Use this component within a sortable component's child (item) component.
21+
22+
```tsx
23+
import Sortable from 'react-native-sortables';
24+
25+
// ... other components
26+
<Sortable.Handle>
27+
{/* ... other components */}
28+
<HandleComponent />
29+
{/* ... other components */}
30+
</Sortable.Handle>;
31+
// ... other components
32+
```
33+
34+
:::important
35+
36+
To use a custom handle component, you **must** set the `customHandle` prop on the sortable component.
37+
38+
:::
39+
40+
## Props
41+
42+
### mode
43+
44+
Determines the reordering behavior of the item.
45+
46+
| type | default | required |
47+
| ------------------------------------------- | ------------- | -------- |
48+
| `'draggable' \| 'fixed' \| 'non-draggable'` | `'draggable'` | NO |
49+
50+
- `'draggable'` - the item **can be dragged** and **moves** when other items are reordered.
51+
- `'non-draggable'` - the item **cannot be dragged** but **moves** when other items are reordered.
52+
- `'fixed'` - the item **cannot be dragged** and **does not move** when other items are reordered.
53+
54+
### children
55+
56+
The handle component (can be anything, e.g. an icon, image, etc.).
57+
58+
| type | default | required |
59+
| ----------- | ------- | -------- |
60+
| `ReactNode` | NO | NO |

‎packages/docs/docs/helper-components/layer.mdx‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
sidebar_position: 1
3-
description: ''
2+
sidebar_position: 3
3+
description: 'Component managing zIndex when an item is being dragged'
44
---
55

66
# Layer
@@ -31,19 +31,15 @@ The **Sortable Layer** component should be used only when necessary, i.e. if you
3131
```tsx
3232
import Sortable from 'react-native-sortables';
3333

34-
function MyComponent() {
35-
return (
36-
// ... other components
37-
<Sortable.Layer>
38-
{/* ... other components */}
39-
<Sortable.Grid // or Sortable.Flex
40-
// ... sortable grid props
41-
/>
42-
{/* ... other components */}
43-
</Sortable.Layer>
44-
// ... other components
45-
);
46-
}
34+
// ... other components
35+
<Sortable.Layer>
36+
{/* ... other components */}
37+
<Sortable.Grid // or Sortable.Flex
38+
// ... sortable grid props
39+
/>
40+
{/* ... other components */}
41+
</Sortable.Layer>;
42+
// ... other components
4743
```
4844

4945
## Props

‎packages/docs/docs/helper-components/touchables.mdx‎

Lines changed: 14 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
sidebar_position: 2
3-
description: ''
3+
description: 'Components that work well with sortable component gesture detectors'
44
---
55

66
# Touchables
@@ -24,45 +24,25 @@ Use these components when you need to add **interactive elements** (buttons, lin
2424

2525
## Usage
2626

27-
Use these components withing a sortable component's child (item) component.
27+
:::info
2828

29-
```tsx
30-
import Sortable from 'react-native-sortables';
29+
For the complete usage example, refer to the [Touchables](/grid/examples/touchables) example.
3130

32-
function Item({ item }: { item: string }) {
33-
return (
34-
// ... other components
35-
<Sortable.Pressable
36-
onPress={() => {
37-
console.log('pressed');
38-
}}>
39-
{/* ... other components */}
40-
</Sortable.Pressable>
41-
// ... other components
42-
);
43-
}
44-
```
31+
:::
4532

46-
And, for example, if you use the **Sortable Grid** component:
33+
Use these components withing a sortable component's child (item) component.
4734

4835
```tsx
49-
import { useCallback } from 'react';
5036
import Sortable from 'react-native-sortables';
51-
import type { SortableGridRenderItem } from 'react-native-sortables';
52-
53-
export default function Grid() {
54-
const renderItem = useCallback<SortableGridRenderItem<string>>(
55-
({ item }) => <Item item={item} />,
56-
[]
57-
);
58-
59-
return (
60-
<Sortable.Grid
61-
renderItem={renderItem}
62-
// ... other props
63-
/>
64-
);
65-
}
37+
38+
// ... other components
39+
<Sortable.Pressable
40+
onPress={() => {
41+
console.log('pressed');
42+
}}>
43+
{/* ... other components */}
44+
</Sortable.Pressable>;
45+
// ... other components
6646
```
6747

6848
## Props

‎packages/docs/static/video/grid-custom-handle.mp4‎

833 KB
Binary file not shown.

0 commit comments

Comments
 (0)