Document more updates

Author: satya164

versioned_docs/version-8.x/drawer-navigator.md

@@ -206,6 +206,13 @@ function CustomDrawerContent(props) {
 }
 ```
 
+The `DrawerContentScrollView` component applies safe are insets automatically:
+
+- On iOS, it sets `contentInsetAdjustmentBehavior="automatic"`
+- On other platforms, it adjusts paddings of the scrollable content
+
+You can override the default behavior by passing `contentInsetAdjustmentBehavior='never'` on iOS `contentContainerStyle` with custom paddings on other platforms.
+
 To add additional items in the drawer, you can use the `DrawerItem` component:
 
 ```js name="Custom Drawer Content" snack static2dynamic
@@ -667,12 +674,13 @@ Style object for the component wrapping the screen content.
 
 #### `configureGestureHandler`
 
-Callback to configure the underlying [gesture from `react-native-gesture-handler`](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/gesture). It receives the `gesture` object as an argument:
+Callback to configure the underlying [pan gesture from `react-native-gesture-handler`](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/gesture). It receives the gesture configuration and should return the updated configuration:
 
 ```js
-configureGestureHandler: ({ gesture }) => {
-  return gesture.enableTrackpadTwoFingerGesture(false);
-},
+configureGestureHandler: (config) => ({
+  ...config,
+  enableTrackpadTwoFingerGesture: false,
+}),
 ```
 
 This is not supported on Web.

versioned_docs/version-8.x/elements.md

@@ -711,6 +711,43 @@ A component which provides an abstraction on top of [`Pressable`](https://reactn
 - `pressColor` - Color of material ripple on Android when it's pressed
 - `pressOpacity` - Opacity when it's pressed if material ripple isn't supported by the platform
 
+### `PlatformIcon`
+
+A component that renders an [icon object](icons.md) with a consistent API across platforms. It accepts the following props:
+
+- `icon` - Icon object to render. It can contain an image, an SF Symbol, or a Material Symbol.
+- `size` - Size of the icon.
+- `color` - Color to apply to the icon.
+- `style` - Style object for the icon.
+
+Example:
+
+```js
+import { PlatformIcon } from '@react-navigation/elements';
+import { Platform } from 'react-native';
+
+// ...
+
+<PlatformIcon
+  icon={Platform.select({
+    ios: {
+      type: 'sfSymbol',
+      name: 'person',
+    },
+    android: {
+      type: 'materialSymbol',
+      name: 'person',
+    },
+    default: {
+      type: 'image',
+      source: require('./person.png'),
+    },
+  })}
+  color="tomato"
+  size={24}
+/>;
+```
+
 ### `Button`
 
 A component that renders a button. In addition to [`PlatformPressable`](#platformpressable)'s props, it accepts following additional props:
@@ -721,6 +758,7 @@ A component that renders a button. In addition to [`PlatformPressable`](#platfor
   - `filled`
 - `color` - Color of the button. Defaults to the [theme](themes.md)'s primary color.
 - `icon` - Icon to display before the label. It can be an icon object or a function that returns an icon object or a React element. See [Icons](icons.md) for more details.
+- `loading` - Boolean which controls whether to show a loading indicator instead of the icon. The button is disabled while loading.
 - `disabled` - Boolean which controls whether the button is disabled.
 - `children` - Content to render inside the button. It must be a string or React element that can be nested inside a `Text` component.
 
@@ -734,7 +772,9 @@ It can be used to navigate between screens by specifying a screen name and param
 </Button>
 ```
 
-Or as a regular button:
+When navigating to a screen this way, it automatically shows the loading indicator while the navigation transition is pending. You can pass `loading={false}` to disable the automatic loading indicator.
+
+It can also be used as a regular button:
 
 ```js
 <Button onPress={() => console.log('button pressed')}>Press me</Button>

versioned_docs/version-8.x/link.md

@@ -17,7 +17,7 @@ import { Link } from '@react-navigation/native';
 
 function Home() {
   return (
-    <Link screen="Profile" params={{ id: 'jane' }}>
+    <Link in="Home" screen="Profile" params={{ id: 'jane' }}>
       Go to Jane's profile
     </Link>
   );
@@ -26,4 +26,4 @@ function Home() {
 
 If you want to use your own custom link component, you can use [`useLinkProps`](use-link-props.md) instead.
 
-The `Link` component accepts the [same props as `useLinkProps`](use-link-props.md#options)
+The `Link` component accepts the [same props as `useLinkProps`](use-link-props.md#options).

versioned_docs/version-8.x/stack-navigator.md

@@ -640,6 +640,10 @@ This hook returns values related to the screen's animation. It contains the foll
 
 See [Transparent modals](#transparent-modals) for an example of how to use this hook.
 
+#### `useGestureHandler`
+
+This hook returns the pan gesture for the current Stack screen, or `null` if gestures are not supported on the platform. It can be used to coordinate a custom gesture with the Stack's gesture using the APIs from [`react-native-gesture-handler`](https://docs.swmansion.com/react-native-gesture-handler/docs/gestures/gesture).
+
 ## Animations
 
 You can specify the `animation` option to customize the transition animation for screens being pushed or popped.
@@ -847,6 +851,7 @@ Stack Navigator exposes various options to configure the transition animation wh
   - `containerStyle` - Style for the container view wrapping the card.
   - `cardStyle` - Style for the view representing the card.
   - `overlayStyle` - Style for the view representing the semi-transparent overlay below
+  - `dimStyle` - Style for the dimming view on top of the card content.
   - `shadowStyle` - Style for the view representing the card shadow.
 
   The function receives the following properties in its argument:
@@ -1173,7 +1178,7 @@ import { TransitionSpecs } from '@react-navigation/stack';
 
 - `forHorizontalIOS` - Standard iOS-style slide in from the right.
 - `forVerticalIOS` - Standard iOS-style slide in from the bottom (used for modals).
-- `forModalPresentationIOS` - Standard iOS-style modal animation in iOS 13.
+- `forModalPresentationIOS` - Standard iOS-style modal animation.
 - `forFadeFromBottomAndroid` - Standard Android-style fade in from the bottom for Android Oreo.
 - `forRevealFromBottomAndroid` - Standard Android-style reveal from the bottom for Android Pie.
 

versioned_docs/version-8.x/typescript.md

@@ -335,6 +335,30 @@ function Header() {
 }
 ```
 
+## Using typed links
+
+The [`Link`](link.md), [`Button`](elements.md#button), and [`useLinkProps`](use-link-props.md) APIs are automatically type-checked based on the root navigator type.
+
+By default, the `screen` and `params` props refer to a screen in the root navigator. To link to a screen in the current or a parent navigator, pass the name of the current or parent screen with the `in` prop, similar to the screen name accepted by `useNavigation`.
+
+For example, suppose the `ArticleList` screen is in a stack nested under the `Feed` tab. The `Feed` tab is nested under the `Home` screen in the root navigator, alongside the `Settings` screen:
+
+```tsx
+function ArticleListScreen() {
+  return (
+    <>
+      {/* The root navigator is used by default */}
+      <Link screen="Settings">Go to Settings</Link>
+
+      {/* The navigator containing the Feed screen is used */}
+      <Link in="Feed" screen="Profile" params={{ userId: 'jane' }}>
+        Go to Jane's profile
+      </Link>
+    </>
+  );
+}
+```
+
 ## Nesting a dynamic navigator
 
 If you render a dynamic navigator inside a static navigator, see [Mixing Static & Dynamic APIs](combine-static-with-dynamic.md#static-root-navigator-dynamic-nested-navigator) for the additional typing and linking configuration needed for the nested navigator.
@@ -558,6 +582,30 @@ function Header() {
 }
 ```
 
+<h2 id="using-typed-links-dynamic">Using typed links</h2>
+
+The [`Link`](link.md), [`Button`](elements.md#button), and [`useLinkProps`](use-link-props.md) APIs are automatically type-checked based on the root navigator type.
+
+By default, the `screen` and `params` props refer to a screen in the root navigator. To link to a screen in the current or a parent navigator, pass the name of the current or parent screen with the `in` prop, similar to the screen name accepted by `useNavigation`.
+
+For example, suppose the `ArticleList` screen is in a stack nested under the `Feed` tab. The `Feed` tab is nested under the `Home` screen in the root navigator, alongside the `Settings` screen:
+
+```tsx
+function ArticleListScreen() {
+  return (
+    <>
+      {/* The root navigator is used by default */}
+      <Link screen="Settings">Go to Settings</Link>
+
+      {/* The navigator containing the Feed screen is used */}
+      <Link in="Feed" screen="Profile" params={{ userId: 'jane' }}>
+        Go to Jane's profile
+      </Link>
+    </>
+  );
+}
+```
+
 ## Annotating `options` and `screenOptions`
 
 When you pass the `options` to a `Screen` or `screenOptions` prop to a `Navigator` component, they are already type-checked and you don't need to do anything special. However, sometimes you might want to extract the options to a separate object, and you might want to annotate it.

versioned_docs/version-8.x/upgrading-from-7.x.md

@@ -726,6 +726,42 @@ Previously, the `gestureResponseDistance` option in Stack Navigator accepted an
 + gestureResponseDistance: 50
 ```
 
+#### Stack and Drawer now use Gesture Handler 3
+
+Stack and Drawer navigators now require `react-native-gesture-handler` 3. In addition to the [dependency change](#dependency-changes), APIs for customizing and accessing gestures have changed to match the new Gesture Handler API.
+
+The [`configureGestureHandler`](drawer-navigator.md#configuregesturehandler) option in Drawer Navigator now receives and returns a gesture configuration object instead of a gesture builder:
+
+```diff lang=js
+- configureGestureHandler: (gesture) =>
+-   gesture.enableTrackpadTwoFingerGesture(false),
++ configureGestureHandler: (config) => ({
++   ...config,
++   enableTrackpadTwoFingerGesture: false,
++ }),
+```
+
+The utilities exported by Stack Navigator have also changed:
+
+```diff lang=js
+- import {
+-   GestureHandlerRefContext,
+-   useGestureHandlerRef,
+- } from '@react-navigation/stack';
++ import {
++   GestureHandlerContext,
++   useGestureHandler,
++ } from '@react-navigation/stack';
+```
+
+The [`useGestureHandler`](stack-navigator.md#usegesturehandler) hook returns the pan gesture for the current Stack screen instead of a ref to the gesture handler.
+
+#### Stack modal presentation has changed on iOS 26
+
+The modal presentation in Stack Navigator has been updated to match the latest iOS design on iOS 26 and later. Modal screens now use rounded corners, and the screens underneath are scaled and dimmed.
+
+This applies to screens using [`presentation: 'modal'`](stack-navigator.md#presentation) and the [`forModalPresentationIOS`](stack-navigator.md#cardstyleinterpolators) card style interpolator. If you use a custom card style interpolator for a similar presentation, it can now return a `dimStyle` to render a dimming view on top of the card content.
+
 #### Material Top Tabs and `react-native-tab-view` have been updated to Material Design 3
 
 ##### The tab bar now uses the `primary` variant by default
@@ -1191,6 +1227,20 @@ It's still possible to use these hooks without passing the screen name, same as
 
 See [`useNavigation`](use-navigation.md), [`useRoute`](use-route.md), and [`useNavigationState`](use-navigation-state.md) for more details.
 
+### Links can target screens in the current or a parent navigator
+
+The [`useLinkProps`](use-link-props.md), [`Link`](link.md), and [`Button`](elements.md#button) APIs now accept an [`in`](use-link-props.md#in) prop. It specifies the name of the current or parent screen whose navigator contains the target screen.
+
+For example, a screen nested in the `Home` tab can link to the `Settings` tab in the parent tab navigator:
+
+```js
+<Link in="Home" screen="Settings">
+  Go to Settings
+</Link>
+```
+
+This is similar to how [typed hooks accept the name of the screen](#common-hooks-now-accept-name-of-the-screen). But unlike typed hooks, navigation from `Link` using the `screen` and `params` props doesn't bubble up to parent navigators.
+
 ### New entry can be added to history stack with `pushParams` action
 
 The `pushParams` action updates the params and pushes a new entry to the history stack:
@@ -1572,6 +1622,20 @@ tabBarIcon: Platform.select({
 
 In addition, new `SFSymbol` and `MaterialSymbol` components are exported from `@react-navigation/native` to render these icons directly.
 
+The new [`PlatformIcon`](elements.md#platformicon) component from `@react-navigation/elements` can render an icon object directly. It renders an image, SF Symbol, or Material Symbol based on the icon object:
+
+```js
+<PlatformIcon
+  icon={Platform.select({
+    ios: { type: 'sfSymbol', name: 'person' },
+    android: { type: 'materialSymbol', name: 'person' },
+    default: { type: 'image', source: require('./person.png') },
+  })}
+  color="tomato"
+  size={24}
+/>
+```
+
 See [Icons](icons.md) for more details.
 
 ### `react-native-tab-view` now supports a `renderAdapter` prop for custom adapters
@@ -1607,9 +1671,25 @@ export default function TabViewExample() {
 
 You can also create your own custom adapter by implementing the required interface. See the [`react-native-tab-view` docs](tab-view.md) for more information.
 
-### `Button` from `@react-navigation/elements` now supports disabled state, icons and React elements
+### `Button` from `@react-navigation/elements` now supports more options
+
+The [`Button`](elements.md#button) component now supports loading and disabled states. The `loading` prop shows a loading indicator in place of the icon and disables interaction:
 
-The [`Button`](elements.md#button) component now supports a disabled state.
+```js
+<Button loading={isLoading} onPress={submit}>
+  Submit
+</Button>
+```
+
+When the button navigates to a screen, it automatically shows the loading indicator while the navigation transition is pending. You can pass `loading={false}` to disable the automatic loading indicator.
+
+The `disabled` prop disables interaction and applies a disabled style to the button:
+
+```js
+<Button disabled={isDisabled} onPress={submit}>
+  Submit
+</Button>
+```
 
 It also accepts an `icon` prop to show an icon alongside the button label:
 

versioned_docs/version-8.x/use-link-props.md

@@ -15,8 +15,22 @@ import { useLinkProps } from '@react-navigation/native';
 
 // ...
 
-const LinkButton = ({ screen, params, action, href, children, ...rest }) => {
-  const props = useLinkProps({ screen, params, action, href });
+const LinkButton = ({
+  in: parent,
+  screen,
+  params,
+  action,
+  href,
+  children,
+  ...rest
+}) => {
+  const props = useLinkProps({
+    in: parent,
+    screen,
+    params,
+    action,
+    href,
+  });
 
   const [isHovered, setIsHovered] = React.useState(false);
 
@@ -64,6 +78,20 @@ If you want to navigate to a nested screen, you can pass the name of the `screen
 </LinkButton>
 ```
 
+### `in`
+
+By default, the link targets a screen in the root navigator. You can pass the name of the current or parent screen whose navigator contains the target screen with the `in` prop.
+
+For example, if the current screen is nested in the `Home` tab, you can link to the `Settings` tab in the parent tab navigator:
+
+```js
+<LinkButton in="Home" screen="Settings">
+  Go to Settings
+</LinkButton>
+```
+
+This is similar to how [useNavigation](use-navigation.md) accepts the current screen or any of its parent screens. But unlike navigating with `useNavigation`, navigation from `Link` using the `screen` and `params` props doesn't bubble up to parent navigators.
+
 ### `action`
 
 Sometimes we want a different behavior for in-page navigation, such as `replace` instead of `navigate`. We can use the `action` prop to customize it:
@@ -88,7 +116,9 @@ function Home() {
 }
 ```
 
-The `screen` and `params` props can be omitted if the `action` prop is specified. In that case, we recommend specifying the `href` prop as well to ensure that the link is accessible.
+The action gets dispatched to the current navigator and can bubble upto a parent navigator similar to dispatching the action with [navigation.dispatch](navigation-object.md#dispatch).
+
+The `screen` and `params` props can be omitted if the `action` prop is specified. In that case, we recommend specifying the `href` prop as well to ensure that the link is accessible. The `in` prop is not supported when only the `action` prop is specified.
 
 ### `href`