[Docs] Add "Getting Started" page (#4362)

m-bert · j-piasecki · web-flow · commit 8896a635b714 · 2026-07-30T10:53:38.000+02:00
## Description

This PR:

- Removes **Introduction** and **Installation** pages
- Adds new "Getting started" page, which is a combination of the two
mentioned above
- Makes `npm` default tab in **Setup** section
- Adds "Your first gesture" section
- Fixes ordering of pages in side bar

## Test plan

Read docs 🤓

---------

Co-authored-by: Jakub Piasecki &lt;jakub.piasecki@swmansion.com&gt;
diff --git a/packages/docs-gesture-handler/docs/fundamentals/animated-interactions.mdx b/packages/docs-gesture-handler/docs/fundamentals/animated-interactions.mdx
@@ -2,7 +2,7 @@
 id: animated-interactions
 title: Integration with Animated
 sidebar_label: Integration with Animated
-sidebar_position: 8
+sidebar_position: 7
 ---
 
 Using hook API allows for smooth integration with the [Animated API](https://reactnative.dev/docs/animated) by allowing for passing an `Animated.event` as the argument to the [`onUpdate`](/docs/fundamentals/callbacks-events#onupdate) callback. The event mapping of `Animated.event` depends on the [`useNativeDriver`](https://reactnative.dev/docs/animated#using-the-native-driver) property.
diff --git a/packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx b/packages/docs-gesture-handler/docs/fundamentals/callbacks-events.mdx
@@ -2,7 +2,7 @@
 id: callbacks-events
 title: Gesture callbacks & events
 sidebar_label: Gesture callbacks & events
-sidebar_position: 5
+sidebar_position: 4
 ---
 
 import {
diff --git a/packages/docs-gesture-handler/docs/fundamentals/gesture-detector.mdx b/packages/docs-gesture-handler/docs/fundamentals/gesture-detector.mdx
@@ -2,7 +2,7 @@
 id: gesture-detectors
 title: Gesture Detectors
 sidebar_label: Gesture detectors
-sidebar_position: 4
+sidebar_position: 3
 ---
 
 ## Gesture Detector
diff --git a/packages/docs-gesture-handler/docs/fundamentals/getting-started.mdx b/packages/docs-gesture-handler/docs/fundamentals/getting-started.mdx
@@ -1,41 +1,40 @@
 ---
-id: installation
-title: Installation
-sidebar_position: 2
+id: getting-started
+title: Getting started
+sidebar_position: 1
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
 import { GestureHandlerCompatibility } from '../../components/Compatibility';
 
-## Requirements
+Gesture Handler provides a declarative API exposing the native platform's touch and gesture system to React Native. It's designed to be a replacement of React Native's built in touch system called [Gesture Responder System](http://reactnative.dev/docs/gesture-responder-system). Using native touch handling allows addressing the performance limitations of React Native's Gesture Responder System. It also provides more control over the platform's native components that can handle gestures on their own.
 
-### Compatibility with React Native versions
+## Installation
+
+### Requirements
+
+#### Compatibility with React Native versions
 
 `react-native-gesture-handler` supports the three latest minor releases of `react-native`.
 
 <GestureHandlerCompatibility spacerAfterIndex={1} />
 
-### Running gestures on the UI thread
+#### Running gestures on the UI thread
 
 Using Reanimated is the recommended method of handling gesture-driven interactions on the UI thread. In order to use it, you need to install [`react-native-reanimated`](https://docs.swmansion.com/react-native-reanimated/) along with [`react-native-worklets`](https://docs.swmansion.com/react-native-worklets/). Another approach is to use React Native's [Animated API](https://reactnative.dev/docs/animated).
 
 For more details on how to implement these, refer to the dedicated sections for [Reanimated](/docs/fundamentals/reanimated-interactions) and [Animated](/docs/fundamentals/animated-interactions).
 
-## Setup
+### Setup
 
 Setting up `react-native-gesture-handler` is pretty straightforward:
 
-### 1. Start with installing the package from npm:
+#### 1. Start with installing the package from npm:
 
 <Tabs groupId="package-managers">
-  <TabItem value="expo" label="EXPO" default>
-    ```bash
-    npx expo install react-native-gesture-handler
-    ```
-  </TabItem>
-  <TabItem value="npm" label="NPM">
+  <TabItem value="npm" label="NPM" default>
     ```bash
     npm install react-native-gesture-handler
     ```
@@ -45,9 +44,14 @@ Setting up `react-native-gesture-handler` is pretty straightforward:
     yarn add react-native-gesture-handler
     ```
   </TabItem>
+  <TabItem value="expo" label="EXPO">
+    ```bash
+    npx expo install react-native-gesture-handler
+    ```
+  </TabItem>
 </Tabs>
 
-### 2. Wrap your app with GestureHandlerRootView component
+#### 2. Wrap your app with GestureHandlerRootView component
 
 ```jsx
 import { GestureHandlerRootView } from 'react-native-gesture-handler';
@@ -64,7 +68,7 @@ Keep `GestureHandlerRootView` as close to the actual root of the app as possible
 
 Check out [`GestureHandlerRootView`](/docs/fundamentals/root-view) section for more details.
 
-### 3. Platform specific setup
+#### 3. Platform specific setup
 
 #### [Expo development build](https://docs.expo.dev/develop/development-builds/introduction/)
 
@@ -74,7 +78,7 @@ When using an Expo development build, run prebuild to update the native code in
 npx expo prebuild
 ```
 
-#### Android
+##### Android
 
 Setting up Gesture Handler on Android doesn't require any more steps. Keep in mind that if you want to use gestures in [Modals](https://reactnative.dev/docs/modal) you need to wrap Modal's content with `GestureHandlerRootView`:
 
@@ -91,27 +95,27 @@ export function CustomModal({ children, ...rest }) {
 }
 ```
 
-#### iOS
+##### iOS
 
 While developing for iOS, make sure to install [pods](https://cocoapods.org/) first before running the app:
 
 ```bash
 cd ios && bundle install && bundle exec pod install && cd ..
 ```
 
-#### macOS
+##### macOS
 
 While developing for macOS, make sure to install [pods](https://cocoapods.org/) first before running the app:
 
 ```bash
 cd macos && bundle install && bundle exec pod install && cd ..
 ```
 
-#### Web
+##### Web
 
 There is no additional configuration required for the web.
 
-#### With [wix/react-native-navigation](https://github.com/wix/react-native-navigation)
+##### With [wix/react-native-navigation](https://github.com/wix/react-native-navigation)
 
 If you are using a native navigation library like [wix/react-native-navigation](https://github.com/wix/react-native-navigation) you need to make sure that every screen is wrapped with `GestureHandlerRootView`. This can be done for example at the stage when you register your screens. Here's an example:
 
@@ -121,7 +125,7 @@ import FirstTabScreen from './FirstTabScreen';
 import SecondTabScreen from './SecondTabScreen';
 import PushedScreen from './PushedScreen';
 
-// register all screens of the app (including internal ones)
+// Register all screens of the app (including internal ones)
 export function registerScreens() {
   Navigation.registerComponent(
     'example.FirstTabScreen',
@@ -160,3 +164,52 @@ export function registerScreens() {
 ```
 
 You can check out [this example project](https://github.com/henrikra/nativeNavigationGestureHandler) to see this kind of set up in action.
+
+## Your first gesture
+
+With the setup done, you're ready to add your first gesture. Create a tap gesture with the [`useTapGesture`](/docs/gestures/use-tap-gesture) hook, attach it to a component with [`GestureDetector`](/docs/fundamentals/gesture-detectors#gesture-detector). Don't forget to wrap your app with [`GestureHandlerRootView`](/docs/fundamentals/root-view), as described in [previous section](/docs/fundamentals/getting-started#2-wrap-your-app-with-gesturehandlerrootview-component).
+
+<CollapsibleCode
+label="Show full example"
+expandedLabel="Hide full example"
+lineBounds={[1, 21]}
+src={`
+import { StyleSheet, View } from 'react-native';
+import {
+  GestureDetector,
+  GestureHandlerRootView,
+  useTapGesture,
+} from 'react-native-gesture-handler';
+
+export default function App() {
+  const tap = useTapGesture({
+    onActivate: () => {
+      console.log('Tapped!');
+    },
+  });
+
+  return (
+    <GestureHandlerRootView style={styles.container}>
+      <GestureDetector gesture={tap}>
+        <View style={styles.box} />
+      </GestureDetector>
+    </GestureHandlerRootView>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  box: {
+    width: 80,
+    height: 80,
+    backgroundColor: '#b58df1',
+    borderRadius: 12,
+  },
+});
+`}/>
+
+That's it! The gesture fires `onActivate` whenever a tap is recognized. Check out [Gesture callbacks & events](/docs/fundamentals/callbacks-events) for the full set of callbacks, or browse [all gestures](/docs/category/gestures) to keep exploring.
diff --git a/packages/docs-gesture-handler/docs/fundamentals/introduction.md b/packages/docs-gesture-handler/docs/fundamentals/introduction.md
diff --git a/packages/docs-gesture-handler/docs/fundamentals/reanimated-interactions.mdx b/packages/docs-gesture-handler/docs/fundamentals/reanimated-interactions.mdx
@@ -2,7 +2,7 @@
 id: reanimated-interactions
 title: Integration with Reanimated
 sidebar_label: Integration with Reanimated
-sidebar_position: 7
+sidebar_position: 6
 ---
 
 [`GestureDetector`](/docs/fundamentals/gesture-detectors) will decide whether to use [Reanimated](https://docs.swmansion.com/react-native-reanimated/) to process provided gestures based on their configuration. If any of the callbacks is a [worklet](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary/#worklet) and Reanimated is not explicitly [turned off](#disabling-reanimated), tools provided by the Reanimated will be utilized, bringing the ability to handle gestures synchronously on the main thread.
diff --git a/packages/docs-gesture-handler/docs/fundamentals/root-view.mdx b/packages/docs-gesture-handler/docs/fundamentals/root-view.mdx
@@ -2,7 +2,7 @@
 id: root-view
 title: GestureHandlerRootView
 sidebar_label: GestureHandlerRootView
-sidebar_position: 3
+sidebar_position: 2
 ---
 
 `GestureHandlerRootView` is a key component that enables Gesture Handler to intercept touch events, allowing for the implementation of gestures in your app. It should wrap your app's main component, and any component that relies on Gesture Handler's gestures has to be a descendant of this view. For more detailed information, you can check out the [under-the-hood section](/docs/under-the-hood/how-does-it-work#android).
diff --git a/packages/docs-gesture-handler/docs/fundamentals/state-manager.mdx b/packages/docs-gesture-handler/docs/fundamentals/state-manager.mdx
@@ -2,7 +2,7 @@
 id: state-manager
 title: State manager
 sidebar_label: State manager
-sidebar_position: 6
+sidebar_position: 5
 ---
 
 RNGH3 allows manually controlling the [gestures' lifecycle](/docs/under-the-hood/state) by using [`GestureStateManager`](#gesturestatemanager).
diff --git a/packages/docs-gesture-handler/docs/guides/troubleshooting.mdx b/packages/docs-gesture-handler/docs/guides/troubleshooting.mdx
@@ -15,7 +15,7 @@ Thanks for giving this library a try! We are sorry that you might have encounter
 2. When sure your problem hasn't been reported or was reported but the proposed solution doesn't work for you please follow [our issue reporting guidelines](#reporting-issues).
 3. You can try seeking help on [Software Mansion Discord](https://discord.com/invite/VemJ4df8Yr).
 4. If you feel like reading the source code we highly recommend it, as this is by far the best resource and gives you the most up to date insights into how the library works and what might be causing the bug.
-5. If you managed to find the solution consider [contributing](/docs/fundamentals/introduction#contributing) a fix or update our documentation to make this information easier to find for others in the future.
+5. If you managed to find the solution consider contributing a fix or update our documentation to make this information easier to find for others in the future.
 
 ## Reporting issues
 
diff --git a/packages/docs-gesture-handler/docusaurus.config.js b/packages/docs-gesture-handler/docusaurus.config.js
@@ -81,7 +81,7 @@ const config = {
         },
       }),
     ],
-    require.resolve('@swmansion/t-rex-ui/preset')
+    require.resolve('@swmansion/t-rex-ui/preset'),
   ],
 
   themeConfig:
@@ -104,7 +104,7 @@ const config = {
         },
         items: [
           {
-            to: 'docs/fundamentals/introduction',
+            to: 'docs/fundamentals/getting-started',
             activeBasePath: 'docs',
             label: 'Docs',
             position: 'right',
diff --git a/packages/docs-gesture-handler/redirects.json b/packages/docs-gesture-handler/redirects.json
diff --git a/packages/docs-gesture-handler/src/components/Hero/StartScreen/index.tsx b/packages/docs-gesture-handler/src/components/Hero/StartScreen/index.tsx
diff --git a/packages/docs-gesture-handler/src/theme/NotFound/mapLegacyUrl.js b/packages/docs-gesture-handler/src/theme/NotFound/mapLegacyUrl.js
