diff --git a/.changeset/cool-spies-study.md b/.changeset/cool-spies-study.md new file mode 100644 index 0000000000..d5fe62437a --- /dev/null +++ b/.changeset/cool-spies-study.md @@ -0,0 +1,25 @@ +--- +'@shopify/hydrogen': minor +--- + +Add `scroll` prop to `Link` and `navigate` to allow the scroll restoration behavior to be disabled. + +By default, when a `` component is clicked, Hydrogen emulates default browser behavior and attempts to restore the scroll position previously used in the visitor's session. For new pages, this defaults to scrolling to the top of the page. + +However, if you are building a user interface that should fetch a new server components request and update the URL but not modify scroll position, then you can disable scroll restoration using the `scroll` prop: + +```jsx +import {Link} from '@shopify/hydrogen'; +export default function Index({request}) { + const url = new URL(request.normalizedUrl); + + return ( + <> +
Current param is: {url.searchParams.get('param')}
+ + Update param to foo + + > + ); +} +``` diff --git a/docs/components/framework/link.md b/docs/components/framework/link.md index 3123a0e70d..4b6515d3f9 100644 --- a/docs/components/framework/link.md +++ b/docs/components/framework/link.md @@ -19,6 +19,32 @@ export default function Index() { {% endcodeblock %} +## Scroll restoration + +By default, when you click a `` component, Hydrogen emulates default browser behavior and attempts to restore the scroll position that was previously used in the visitor's session. For new pages, the `` component defaults to scrolling to the top of the page. + +However, if you want to build a user interface that re-renders server components and updates the URL, but doesn't modify the scroll position, then you can disable scroll restoration using the `scroll` prop: + +{% codeblock file, filename: 'index.server.jsx' %} + +```jsx +import {Link} from '@shopify/hydrogen'; +export default function Index({request}) { + const url = new URL(request.normalizedUrl); + + return ( + <> +Current param is: {url.searchParams.get('param')}
+ + Update param to foo + + > + ); +} +``` + +{% endcodeblock %} + ## Props | Name | Type | Description | @@ -28,6 +54,7 @@ export default function Index() { | clientState? |any | The custom client state with the navigation. |
| reloadDocument? | boolean | Whether to reload the whole document on navigation. |
| prefetch? | boolean | Whether to prefetch the link source when the user signals intent. Defaults to `true`. For more information, refer to [Prefetching a link source](https://shopify.dev/custom-storefronts/hydrogen/framework/routes#prefetching-a-link-source). |
+| scroll? | boolean | Whether to emulate natural browser behavior and restore scroll position on navigation. Defaults to `true`. |
## Component type
diff --git a/docs/hooks/framework/usenavigate.md b/docs/hooks/framework/usenavigate.md
index a2cf74950b..4cbe2f1bc5 100644
--- a/docs/hooks/framework/usenavigate.md
+++ b/docs/hooks/framework/usenavigate.md
@@ -27,24 +27,14 @@ export default function ClientComponent() {
{% endcodeblock %}
-## Arguments
-
-The `useNavigate` hook takes the following arguments:
-
-| Argument | Description |
-| --------------- | ------------------------------------------------------------------------------------------ |
-| replace? | Whether to update the state object or URL of the current history entry. Defaults to false. |
-| reloadDocument? | Whether to reload the whole document on navigation. |
-| clientState? | The custom client state with the navigation. |
-
## Return value
-The `useNavigate` hook returns the following values:
+The `useNavigate` hook returns a function which accepts the following values:
-| Name | Description |
-| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| path | The path you want to navigate to. |
-| options | The options for the configuration object: `replace`, `reloadDocument`, `clientState`. For more information the options, refer to the [Link component](https://shopify.dev/api/hydrogen/components/framework/link). |
+| Name | Description |
+| ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| path | The path you want to navigate to. |
+| options | The options for the configuration object: `replace`, `reloadDocument`, `clientState`, `scroll`. For more information the options, refer to the [Link component](https://shopify.dev/api/hydrogen/components/framework/link). |
## Considerations
diff --git a/packages/hydrogen/src/components/Link/Link.client.tsx b/packages/hydrogen/src/components/Link/Link.client.tsx
index cd82d4bd08..a2f8acc353 100644
--- a/packages/hydrogen/src/components/Link/Link.client.tsx
+++ b/packages/hydrogen/src/components/Link/Link.client.tsx
@@ -17,6 +17,8 @@ export interface LinkProps
reloadDocument?: boolean;
/** Whether to prefetch the link source when the user signals intent. Defaults to `true`. For more information, refer to [Prefetching a link source](https://shopify.dev/custom-storefronts/hydrogen/framework/routes#prefetching-a-link-source). */
prefetch?: boolean;
+ /** Whether to emulate natural browser behavior and restore scroll position on navigation. Defaults to `true`. */
+ scroll?: boolean;
}
/**
@@ -44,6 +46,7 @@ export const Link = React.forwardRef