Change Log

All notable changes to this project will be documented in this file. See Conventional Commits for commit guidelines.

7.0.0-rc.14 (2024-09-08)

Bug Fixes

improve error message when navigating with invalid screen name (9f2c310) - by @satya164

7.0.0-rc.13 (2024-08-07)

Bug Fixes

improve how navigate and other methods are typed (#12093) (a528b9b) - by @satya164

7.0.0-rc.12 (2024-08-05)

Bug Fixes

allow undefined in path config validation (#12085) (4f20056) - by @janicduplessis

7.0.0-rc.11 (2024-08-01)

Note: Version bump only for package @react-navigation/core

7.0.0-rc.10 (2024-07-11)

Bug Fixes

upgrade react-native-builder-bob (1575287) - by @

7.0.0-rc.9 (2024-07-11)

Bug Fixes

preserve order when reading screens and groups (4a928f9) - by @

7.0.0-rc.8 (2024-07-10)

Bug Fixes

bump use-latest-callback to fix require (40ddae9) - by @satya164

7.0.0-rc.7 (2024-07-07)

Bug Fixes

upgrade use-latest-callback for esm compat (187d41b) - by @satya164

7.0.0-rc.6 (2024-07-04)

Bug Fixes

fix published files (829caa0) - by @

7.0.0-rc.5 (2024-07-04)

Note: Version bump only for package @react-navigation/core

7.0.0-rc.4 (2024-07-04)

Features

add package.json exports field (1435cfe) - by @

7.0.0-rc.3 (2024-07-01)

Bug Fixes

stop using react-native field in package.json (efc33cb) - by @

7.0.0-rc.2 (2024-06-29)

Bug Fixes

add a workaround for incorrect inference #12041 (85c4bbb) - by @
fix type error with listeners for static config (54437e2) - by @satya164

7.0.0-rc.1 (2024-06-28)

Features

make NavigationContainerRef.getCurrentRoute type safe (#11525) (9bedc0c) - by @lucasloisp

7.0.0-rc.0 (2024-06-27)

Bug Fixes

throw proper error if invalid initialRouteName is passed (e86f3b4) - by @satya164

7.0.0-alpha.17 (2024-03-22)

Bug Fixes

accept partial linking.config for static navigation (3825046) - by @satya164

Features

add automatic home screen detection for auto linking (b0bec6f) - by @satya164

7.0.0-alpha.16 (2024-03-22)

Features

add a way to automatically generate linking config (d090836) - by @satya164
automatically enable linking if any config is specified (c91d247) - by @satya164

7.0.0-alpha.15 (2024-03-20)

Bug Fixes

only replace trailing slash on decode (#11899) (31bb8a1) - by @cranberyxl

Features

add getStateForRouteNamesChange to all navigators and mark it as unstable (4edbb07) - by @satya164

7.0.0-alpha.14 (2024-03-14)

Features

automatically infer types for navigation in options, listeners etc. (#11883) (c54baf1) - by @satya164

7.0.0-alpha.13 (2024-03-10)

Features

deep freeze state to avoid issues due to mutation (2a5721b) - by @satya164

7.0.0-alpha.12 (2024-03-09)

Bug Fixes

fix handling groups with linking config and types (a847715) - by @satya164
fix incomplete types for screen listeners (5f0e2aa), closes #11293 - by @satya164

7.0.0-alpha.11 (2024-03-08)

Bug Fixes

adjust URL encoding to avoid encoding unnecessarily (#11867) (7991ce8) - by @groot007
fix navigation not working in strict mode (11dbba9) - by @satya164
handle conflicting nested path params for linking (#11849) (aeaadd6) - by @rexfordessilfie
linking on initial path plus wildcard (#11844) (2c2881f), closes /github.com/react-navigation/react-navigation/blob/fe4d4289e2bdec7614c6f2e5ca95d9b8f714af39/packages/core/src/getStateFromPath.tsx#L138 - by @rexfordessilfie

7.0.0-alpha.10 (2024-03-04)

Bug Fixes

don't throw on setParams on ref (b99d3c3) - by @satya164

7.0.0-alpha.9 (2024-02-23)

Bug Fixes

type errors when getState used outside of a screen (#11827) (b3512a5), closes #11701 - by @MrRefactor

7.0.0-alpha.8 (2024-02-23)

Bug Fixes

handle non-function screens in static navigation (7ba61f2) - by @satya164
throw if screens property isn't specified in static config (a5fc69e) - by @satya164

7.0.0-alpha.7 (2024-01-17)

Features

add a new 'describe' method to create placeholder descriptor (#11726) (0b83a9b) - by @osdnk
add layout and screenLayout props for screens (#11741) (2dc2178) - by @satya164
move theming to core and pass theme to options (#11707) (8e7ac4f) - by @satya164
preloading for stack navigator (#11733) (14fa6df), closes #11702 #11727 - by @osdnk
preloading in routers (382d6e6) - by @osdnk

7.0.0-alpha.6 (2023-11-17)

Note: Version bump only for package @react-navigation/core

7.0.0-alpha.5 (2023-11-12)

Bug Fixes

cannot resolve use-latest-callback (#11696) (361bc6a) - by @jkaveri
onReady not getting called on native (#11628) (67232f1) - by @osdnk
fix!: don't use screen from params as initialRouteName (#11680) (4b681a9), closes #11680 - by @satya164

Features

add useUnhandledLinking for handling deep links behind auth etc. (#11602) (688c43a), closes #10939 - by @osdnk
add a layout prop for navigators (#11614) (1f51190) - by @satya164
add API for unhandled linking (#11672) (5758b26) - by @osdnk

BREAKING CHANGES

Previously when using nested navigation API, we used that screen as initialRouteName.

e.g.

navigation.navigate('MyScreen', { screen: 'NestedScreen' });

Here, the 'NestedScreen' will be set as initialRouteName.

It has the result of rendering the navigator with that screen as focused screen. While this behaviour is expected, that screen was also used as the initialRouteName for every other operation ignoring the initialRouteName prop - which is not expected.

This change refactors the way the focused screen for initial render is set to avoid this behavior.

7.0.0-alpha.4 (2023-09-25)

Note: Version bump only for package @react-navigation/core

7.0.0-alpha.3 (2023-09-07)

Bug Fixes

avoid re-rendering screen when nested navigator state changes (#11547) (2c0f604) - by @okwasniewski
PathConfigMap type error: Type 'T' does not satisfy the constrai… (#11238) (8e8ad0c) - by @AntonYushkevich

Features

allow full linking config in static config (ba53154) - by @satya164

BREAKING CHANGES

This breaks getFocusedRouteNameFromRoute inside components as it requires a re-render to get the new value. However, it still works in options callback which is its intended use case.

7.0.0-alpha.2 (2023-06-22)

Bug Fixes

fix infering params when a screen is in a group (5e9f001), closes #11325 - by @satya164

Code Refactoring

drop custom fromEntries in favor of Object.fromEntries (9fe34b4), closes /reactnative.dev/blog/2022/06/21/version-069#highlights-of-069 - by @satya164

Features

support a top-level path configuration in linking config (1d0297e) - by @satya164

BREAKING CHANGES

this means we now require at least iOS 12.2 and React Native 0.69 whose minimum supported iOS version is 12.4

7.0.0-alpha.1 (2023-03-01)

Bug Fixes

fix paths in sourcemap files (368e069) - by @satya164
properly export types to avoid webpack warning (4f597a8) - by @satya164

7.0.0-alpha.0 (2023-02-17)

Bug Fixes

bump query-string version (#11069) (e6c05e2) - by @krudos
fix type of setOptions and mark data passed to callbacks as Readonly (6655c66) - by @satya164
remove defaultScreenOptions from default navigator options (6267952) - by @satya164
support dispatching action to child without 'navigationInChildEnabled' if 'target' is specified (debd620) - by @satya164
fix!: align onReady callback and navigationRef.isReady (1959baa) - by @satya164
feat!: add popTo method for stack and remove going back behaviour of (c9c2163) - by @satya164
refactor!: drop support for key property in navigate (61c53bb) - by @satya164

Features

add navigateDeprecated for backward compatibility (8ea6dc7) - by @satya164
extract drawer to a separate package (58b7cae) - by @satya164
support statically confguring navigation tree (#11144) (4cc322e) - by @satya164

BREAKING CHANGES

Previously, the onReady prop and navigationRef.isReady() work slightly differently. The onReady callback fired when NavigationContainer finishes mounting and deep links is resolved. The navigationRef.isReady() method additionally checks if there are any navigators rendered - which may not be true if the user is rendering their navigators conditionally inside a NavigationContainer.

This changes onReady to work similar to navigationRef.isReady(). The onReady callback will now fire only when there are navigators rendered - reflecting the value of navigationRef.isReady().

Previously, navigate method navigated back if the screen already exists in the stack. I have seen many people get confused by this behavior. This behavior is also used for sending params to a previous screen in the documentation. However, it's also problematic since it could either push or pop the screens based on the scenario.

This removes the going back behavior from navigate and adds a new method popTo to go back to a specific screen in the stack.

The methods now behave as follows:

navigate(screenName) will stay on the current screen if the screen is already focused, otherwise push a new screen to the stack.
popTo(screenName) will go back to the screen if it exists in the stack, otherwise pop the current screen and add this screen to the stack.
To achieve the previous behavior with navigate, you can use the getId prop in which case it'll go to the screen with the matching ID and push or pop screens accordingly.

Previously, you could specify a route key to navigate to, e.g. navigation.navigate({ key: 'someuniquekey' }). It's problematic since key is an internal implementation detail and created by the library internally - which makes it weird to use. None of the other actions support such usage either.

In addition, we have already added a better API (getId) which can be used for similar use cases - and gives users full control since they provide the ID and it's not autogenerated by the library.

So this change removes the key option from the navigate action.

6.4.1 (2022-11-21)

Bug Fixes

add accessibility props to NativeStack screens (#11022) (3ab05af)

6.4.0 (2022-09-16)

Bug Fixes

add missing parentheses typo in useFocusEffect error message (#10688) (9203045)
handle path with empty string properly for linking (#10708) (e8c374e)
potential prototype pollution attacks (#10455) (10e5d2b)
prevent Object properties to be used as parsing functions (#10570) (7fbd3e5)
strongly type the component prop on RouteConfigComponent (#10519) (55da7c9)
wrong setParams type if route does not have params (#10512) (8ed42cd)

Features

implement usePreventRemove hook (#10682) (7411516)

6.3.0 (2022-08-24)

Bug Fixes

add missing parentheses typo in useFocusEffect error message (#10688) (9203045)
handle path with empty string properly for linking (#10708) (e8c374e)
potential prototype pollution attacks (#10455) (10e5d2b)
prevent Object properties to be used as parsing functions (#10570) (7fbd3e5)
strongly type the component prop on RouteConfigComponent (#10519) (55da7c9)
wrong setParams type if route does not have params (#10512) (8ed42cd)

Features

implement usePreventRemove hook (#10682) (7411516)

6.2.2 (2022-07-05)

Bug Fixes

ensure same @types/react version in repo (#10663) (e662465), closes #10655
make event listeners idempotent (#10667) (3bb31e9), closes #10664

6.2.1 (2022-04-01)

Bug Fixes

return undefined instead of throwing when parent is not found (28a3993)

6.2.0 (2022-04-01)

Features

add an ID prop to navigators (4e4935a)

6.1.1 (2022-01-29)

Bug Fixes

removal of non-existing listener should not break updating ref (#10067) (d206ffe)
warn for components starting with lower case names (4b4a7c5)

6.1.0 (2021-10-12)

Features

add a navigationKey prop to Screen and Group (b2fa62c)

6.0.3 (2021-10-09)

Note: Version bump only for package @react-navigation/core

6.0.2 (2021-09-26)

Bug Fixes

automatically queue listeners when container isn't ready (acdde18)
change error when using React Navigation 4 API (a802c9d)
update the error message for registering navigators (171d7e1)

6.0.1 (2021-08-03)

Bug Fixes

add merge to the navigate types (#9777) (be8532c)

6.0.0 (2021-08-01)

Bug Fixes

clear options set from a screen when it unmounts. closes #9756 (d2d7f8d)

6.0.0-next.17 (2021-07-16)

Bug Fixes

use nested params for initial state only (577d79e)

6.0.0-next.16 (2021-07-16)

Bug Fixes

prevent navigation state updates after state cleanup (#9688) (16f0e11)
sort wildcard and :params (#9672) (4135d09)

6.0.0-next.15 (2021-07-01)

Bug Fixes

fix typechecking in linking config (b1134c8)

Features

show stack trace in the flipper plugin (97772af)

6.0.0-next.14 (2021-06-10)

Features

show stack trace in the flipper plugin (97772af)

6.0.0-next.13 (2021-05-29)

Bug Fixes

validate property names in linking config (324ea71)

6.0.0-next.12 (2021-05-29)

Bug Fixes

try to fix #9631 (b4d7b0e)

6.0.0-next.11 (2021-05-27)

Note: Version bump only for package @react-navigation/core

6.0.0-next.10 (2021-05-26)

Features

add screenListeners prop on navigators similar to screenOptions (cde44a5)
expose container ref in useNavigation (1d40279)

6.0.0-next.9 (2021-05-23)

Note: Version bump only for package @react-navigation/core

6.0.0-next.8 (2021-05-16)

Bug Fixes

fix type error when passing unannotated navigation ref (dc4ffc0)

6.0.0-next.7 (2021-05-10)

Features

return a NavigationContent component from useNavigationBuilder (1179d56)

6.0.0-next.6 (2021-05-09)

Bug Fixes

fix type annotations for useNavigation (again) (929c3e3)

6.0.0-next.5 (2021-05-09)

Bug Fixes

fix type annotations for useNavigation (7da45e1)

6.0.0-next.4 (2021-05-09)

Features

add a new component to group multiple screens with common options (1a6aebe)
add ability to specify root param list (b28bfdd)

6.0.0-next.3 (2021-05-01)

Features

add a CompositeScreenProps type (def7c03)
add helper and hook for container ref (0ecd112)

6.0.0-next.2 (2021-04-08)

Bug Fixes

properly resolve initialRouteNames (c38906a)

Features

improve useNavigationState typing (#9464) (84020a0)

6.0.0-next.1 (2021-03-10)

Note: Version bump only for package @react-navigation/core

6.0.0-next.0 (2021-03-09)

Bug Fixes

add missing helper types in descriptors (21a1154)
check duplicate names only for immediate nested screens (36a9b4f)
don't merge params on navigation (366d018)
drop dangerously prefix from getState and getParent (227f133)
drop support for legacy linking config (0e13e8d)
fix default screen options not being respected (03ba1f2)
fix incorrect state change events in independent nested container (b82a912), closes #9080
print an error when passing a second argument to useFocusEffect (c361795)
remove the state property from route prop (ebab518)
show redbox instead of crash if navigation isn't initialized (13d8553)

Features

add a way to specify an unique ID for screens (15b8bb3)
add an option to specify default options for the navigator (c85f2ff)
allow returning null or undefined to skip actions with dispatch (d6466b7)
associate path with the route it opens when deep linking (#9384) (86e64fd), closes #9102
warn on duplicate screen names across navigators (02a031e)

BREAKING CHANGES

This commit drops support for legacy linking config which allowed screens to be specified without the screens property in the config.
Previous versions of React Navigation merged params on navigation which caused confusion. This commit changes params not to be merged.

The old behaviour can still be achieved by passing merge: true explicitly:

CommonActions.navigate({
  name: 'bar',
  params: { fruit: 'orange' },
  merge: true,
})

initialParams specified for the screen are always merged.

any code which relies on route.state will break.

Previous versions printed a warning on accessing route.state. This commit removes the property entirely. Accessing this property isn't safe since child navigator state isn't gurranteed to be in sync with parent navigator state and cause subtle bugs in apps.

5.14.3 (2020-11-10)

Bug Fixes

improve the error message for incorrect screen configuration (8f764d8)

5.14.2 (2020-11-09)

Bug Fixes

throw if the same pattern resolves to multiple screens (48b2e77)

5.14.1 (2020-11-08)

Bug Fixes

tweak error message when navigator has non-screen children (360b0e9)

5.14.0 (2020-11-04)

Bug Fixes

always respect key in the route object when generating action (cb2e744)

Features

add a NavigatorScreenParams type. closes #6931 (e3e58c2)
add warning on accessing the state object on route prop (ec7b02a)

5.13.5 (2020-11-04)

Bug Fixes

don't use use-subscription to avoid peer dep related errors (66f3a4a), closes /github.com/react-navigation/react-navigation/issues/9021#issuecomment-721679760
use useDebugValue in more places (b20f2d1)

5.13.4 (2020-11-03)

Bug Fixes

fix nested navigation not working the first time (ebc7f9e)

5.13.3 (2020-11-03)

Bug Fixes

handle navigating to same screen again for nested screens (0945689)

5.13.2 (2020-10-30)

Bug Fixes

fix params from for the root screen when creating action (e8515f9), closes #9006
trim routes if an index is specified in state (fb7ac96)

5.13.1 (2020-10-28)

Bug Fixes

improve types for route prop in screenOptions (d26bcc0)

5.13.0 (2020-10-24)

Bug Fixes

fix imports from query-string. closes #8971 (#8976) (261a33a)

Features

add an unhandled action listener (#8895) (80ff5a9)
allow deep linking to reset state (#8973) (7f3b27a), closes #8952
improve types for navigation state (#8980) (7dc2f58)
update helper types to have navigator specific methods (f51086e)

5.12.5 (2020-10-07)

Note: Version bump only for package @react-navigation/core

5.12.4 (2020-09-22)

Bug Fixes

typo in logic of getStateFromPath (#8868) (97c215d)

5.12.3 (2020-08-04)

Note: Version bump only for package @react-navigation/core

5.12.2 (2020-07-28)

Note: Version bump only for package @react-navigation/core

5.12.1 (2020-07-19)

Bug Fixes

make sure new state events are emitted when new navigators mount (af8b274)

5.12.0 (2020-07-10)

Bug Fixes

avoid error setting warning for devtools migration. closes #8534 (1801a13)
fix bubbling actions to correct target when specified (9671c76)
fix options event being emitted incorrectly (#8559) (a255e35)
improve the warning message for non-serializable values (e63580e)
mark some types as read-only (7c3a0a0)

Features

add a beforeRemove event (6925e92)
add a getComponent prop to lazily specify components (f418029)

5.11.1 (2020-06-25)

Bug Fixes

fix error with type definitions. closes #8511 (d1210a8)

5.11.0 (2020-06-24)

Bug Fixes

fix getCurrentOptions for nested screens (6730690)
fix getCurrentOptions for nested screens (afc83ee)
more improvements to types (d244488)

Features

add devtools package (#8436) (95b044e)
add event for options on container (#8334) (fe3f98e)
add helper to get focused route name from nested state (#8435) (f51f9c8)
rework linking configuration to be more strict (#8502) (a021cfb)

5.10.0 (2020-06-06)

Bug Fixes

catch missing params when they are required in navigate (#8389) (8774ca9)
make sure the wildcard pattern catches nested unmatched routes (c3bd349)
only use the query params for focused route in path (2d66ef9)
prevent state change being emitted unnecessarily (ab1f79c)

Features

add wildcard patterns for paths (4fe72e3), closes #8019

5.9.0 (2020-05-27)

Features

add ref to get current options in ServerContainer (#8333) (0b1a718)

5.8.2 (2020-05-23)

Note: Version bump only for package @react-navigation/core

5.8.1 (2020-05-20)

Note: Version bump only for package @react-navigation/core

5.8.0 (2020-05-20)

Features

add getCurrentOptions (#8277) (d024ec6)
add getCurrentRoute (#8254) (7b25c8e)

5.7.0 (2020-05-16)

Bug Fixes

don't use Object.fromEntries (51f4d11)

Features

add a PathConfig type (60cb3c9)

5.6.1 (2020-05-14)

Bug Fixes

don't use flat since it's not supported in node (21b397f)

5.6.0 (2020-05-14)

Bug Fixes

ignore extra slashes in the pattern (3c47716)
ignore state updates when we're not mounted (0149e85), closes #8226

Features

merge path patterns for nested screens (#8253) (acc9646)

5.5.2 (2020-05-08)

Bug Fixes

fix building typescript definitions. closes #8216 (47a1229)

5.5.1 (2020-05-08)

Bug Fixes

avoid cleaning up state when a new navigator is mounted. fixes #8195 (f6d0676)

5.5.0 (2020-05-05)

Features

add support for optional params to linking (#8196) (fcd1cc6)
support params anywhere in path segement (#8184) (3999fc2)

5.4.0 (2020-04-30)

Bug Fixes

handle empty paths when parsing (c3fa83e)
parsing url (bd35b4f)

Features

add useLinkBuilder hook to build links (2792f43)

5.3.5 (2020-04-27)

Bug Fixes

add config to enable redux devtools integration (c9c825b)

5.3.4 (2020-04-17)

Bug Fixes

add initial option for navigating to nested navigators (004c7d7)
add initial param for actions from deep link (a3f7a5f)
handle initial: false for nested route after first initialization (187aefe)

5.3.3 (2020-04-08)

Bug Fixes

switch order of focus and blur events. closes #7963 (ce3994c)
workaround warning about setState in another component in render (d4fd906)

5.3.2 (2020-03-30)

Bug Fixes

handle no path property and undefined query params (#7911) (cd47915)

5.3.1 (2020-03-23)

Bug Fixes

don't emit events for screens that don't exist anymore (1c00142)
only call listeners for focused screen for global events (3096de6)

5.3.0 (2020-03-22)

Bug Fixes

return correct value for isFocused after changing screens (5b15c71), closes #7843

Features

support function in listeners prop (3709e65)

5.2.3 (2020-03-19)

Note: Version bump only for package @react-navigation/core

5.2.2 (2020-03-16)

Note: Version bump only for package @react-navigation/core

5.2.1 (2020-03-03)

Bug Fixes

fix links for documentation (5bb0f40)
move updating state to useEffect (2dfa4f3)

5.2.0 (2020-02-26)

Features

add ability add listeners with listeners prop (1624108), closes #6756

5.1.6 (2020-02-21)

Bug Fixes

avoid emitting focus events twice (f167008), closes #6749
preserve screen order with numeric names (125bd70), closes #6900

5.1.5 (2020-02-19)

Bug Fixes

show descriptive error for invalid return for useFocusEffect (1a28c29)

5.1.4 (2020-02-14)

Bug Fixes

link to migration guide on invalid usage (c5fcfbd)
return '/' for empty paths (aaf01e0)

5.1.3 (2020-02-14)

Bug Fixes

return false for canGoBack if navigator hasn't finished mounting (c8ac5fa)
throw a descriptive error if navigation object hasn't initialized (b6accd0)
update links in error messages (f964200)

5.1.2 (2020-02-12)

Bug Fixes

fix false positives for circular object check (030c63c), closes #6827
static container memo check (#6825) (2bf0958)

5.1.1 (2020-02-11)

Bug Fixes

don't cleanup state on switching navigator (359ae1b)

5.1.0 (2020-02-10)

Bug Fixes

add some links in the error messages (13b4e07)

Features

support ignoring empty path strings (#349) (61b1134)

5.0.0-alpha.43 (2020-02-04)

Bug Fixes

improve error message for unhandled action (ca4a360)

Features

add initialRouteName property to config (#322) (4ca5cc6)

5.0.0-alpha.42 (2020-02-04)

Note: Version bump only for package @react-navigation/core

5.0.0-alpha.41 (2020-02-03)

Bug Fixes

ignore circular references when checking serializable (e5063b9)

5.0.0-alpha.40 (2020-02-02)

Bug Fixes

add licenses (0c159db)
add warning when passing inline function to component prop (fa4a959)
tweak error messages for validation (2243b45)

Features

add screens prop for nested configs (#308) (b931ae6)
add useIsDrawerOpen hook (#299) (ecd68af)
integrate with history API on web (5a3f835)

5.0.0-alpha.38 (2020-02-02)

Bug Fixes

add licenses (0c159db)
add warning when passing inline function to component prop (fa4a959)
tweak error messages for validation (2243b45)

Features

add screens prop for nested configs (#308) (b931ae6)
add useIsDrawerOpen hook (#299) (ecd68af)
integrate with history API on web (5a3f835)

5.0.0-alpha.37 (2020-01-24)

Bug Fixes

add error message when trying to use v4 API with v5 (179e807)
validate screen configs (2f1f0af)
warn if non-serializable values found in state (5751e7f)

5.0.0-alpha.36 (2020-01-23)

Bug Fixes

disallow canPreventDefault option if not present in types (d9059b5)
don't add ?if query params is empty (3bf5ddd)
fix types for useFocusEffect (23ab45a), closes #270
make sure that we return correct value if selector changes (6c2acbb), closes /github.com/react-navigation/navigation-ex/pull/273#issuecomment-576581225
use protected for private value store (ad4eaff)