From 4a50173ac23598d4d6a9ffb3c7dfb2e599c8dd86 Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 18:19:46 +0200
Subject: [PATCH 01/14] add notes about route and component preloading

---
 src/routes/guides/routing-and-navigation.mdx  |  6 ++---
 .../solid-router/advanced-concepts/data.json  |  2 +-
 .../advanced-concepts/preloading.mdx          | 22 +++++++++++++++++
 .../primitives/use-preload-route.mdx          | 24 +++++++++++++++++--
 4 files changed, 47 insertions(+), 7 deletions(-)
 create mode 100644 src/routes/solid-router/advanced-concepts/preloading.mdx

diff --git a/src/routes/guides/routing-and-navigation.mdx b/src/routes/guides/routing-and-navigation.mdx
index afaedc388f..4d940b8f22 100644
--- a/src/routes/guides/routing-and-navigation.mdx
+++ b/src/routes/guides/routing-and-navigation.mdx
@@ -446,8 +446,7 @@ The preload function is then passed in the `<Route>` definition:
 You can export preload functions and data wrappers that correspond to routes from a dedicated `[route].data.js` or `[route].data.ts` file.
 This pattern provides a way to import the data function without loading anything else.
 
-```jsx
-// src/pages/users/[id].data.js
+```tsx title="src/pages/users/[id].data.js"
 import { query } from "@solidjs/router";
 
 export const getUser = query(async (id) => {
@@ -494,8 +493,7 @@ render(
 `[id].jsx` contains the component that gets rendered.
 When you wrap the function within [`createAsync`](/solid-router/reference/data-apis/create-async) with the imported function, it will yield [a signal](/routes/concepts/signals) once the anticipated promise resolves.
 
-```jsx
-// [id].jsx
+```tsx title="[id].tsx"
 import { createAsync } from "@solidjs/router";
 import { getUser } from "./[id].data";
 
diff --git a/src/routes/solid-router/advanced-concepts/data.json b/src/routes/solid-router/advanced-concepts/data.json
index 0f6e6c5f8e..523931f31b 100644
--- a/src/routes/solid-router/advanced-concepts/data.json
+++ b/src/routes/solid-router/advanced-concepts/data.json
@@ -1,4 +1,4 @@
 {
 	"title": "Advanced concepts",
-	"pages": ["lazy-loading.mdx"]
+	"pages": ["preloading.mdx", "lazy-loading.mdx"]
 }
diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
new file mode 100644
index 0000000000..959b4236a7
--- /dev/null
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -0,0 +1,22 @@
+---
+title: Preloading
+---
+
+When using the [`<A>`](/solid-router/reference/components/a) component from Solid Router, routes are preloaded by default on link hover/focus to improve perceived performance.
+
+To enhance preloading, you can define the `preload` function on your route definition.
+When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to fetch data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
+
+| user action | route behavior                          |
+| ----------- | -------------------------------------- |
+| hover   | with a 300ms delay to avoid excessive preloading  |
+| focus   | immediately                           |
+
+## Imperative Preloading
+
+You can also use the [`usePreloadRoute`](/solid-router/references/use-preload-route) helper to preload routes programmatically in response to events other than link hover/focus, such as button clicks or timers.
+This helper will load only the route's component by default, but it can receive a configuration object to also load the data.
+
+## Preloading and Lazy Loading
+
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/references/use-preload-route) helper in the parent component to load them when needed.
\ No newline at end of file
diff --git a/src/routes/solid-router/reference/primitives/use-preload-route.mdx b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
index 8534db7811..6fe1709913 100644
--- a/src/routes/solid-router/reference/primitives/use-preload-route.mdx
+++ b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
@@ -2,10 +2,30 @@
 title: usePreloadRoute
 ---
 
-`usePreloadRoute` returns a function that can be used to preload a route manually. This is what happens automatically with link hovering and similar focus based behavior, but it is available here as an API.
+`usePreloadRoute` returns a function that can be used to preload a route manually.
 
-```js
+```ts
 const preload = usePreloadRoute();
 
 preload(`/users/settings`, { preloadData: true });
 ```
+
+## Usage
+
+Routes are preloaded by default when using the [`<A>`](/solid-router/reference/components/a)` component.
+This helper is useful when you want to preload a route in response to some other event, such as a button click or a timer.
+
+## Type Signature
+
+### Parameters
+
+| Parameter | Type     | Required | Description                          |
+| --------- | -------- | -------- | ------------------------------------ |
+| `to`      | `To`     | Yes      | The route path to preload            |
+| `options` | `object` | No       | Configuration options for preloading |
+
+### Options
+
+| Option        | Type      | Default | Description                                                         |
+| ------------- | --------- | ------- | ------------------------------------------------------------------- |
+| `preloadData` | `boolean` | `false` | Whether to preload the route's data in addition to the route itself |

From 50d0a0c34dd23766983513234ae77d5ac120b1fa Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 18:35:18 +0200
Subject: [PATCH 02/14] fix backtick typo

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 .../solid-router/reference/primitives/use-preload-route.mdx     | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/solid-router/reference/primitives/use-preload-route.mdx b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
index 6fe1709913..cd7d880ec3 100644
--- a/src/routes/solid-router/reference/primitives/use-preload-route.mdx
+++ b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
@@ -12,7 +12,7 @@ preload(`/users/settings`, { preloadData: true });
 
 ## Usage
 
-Routes are preloaded by default when using the [`<A>`](/solid-router/reference/components/a)` component.
+Routes are preloaded by default when using the [`<A>`](/solid-router/reference/components/a) component.
 This helper is useful when you want to preload a route in response to some other event, such as a button click or a timer.
 
 ## Type Signature

From a2ab4635b02ac5dc4f4a268ab03d7afa81a399ec Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 18:35:35 +0200
Subject: [PATCH 03/14] fix bad URL

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 src/routes/solid-router/advanced-concepts/preloading.mdx | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index 959b4236a7..46e52906d2 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -14,9 +14,9 @@ When on a [SolidStart](/solid-start) application, this function can also run on
 
 ## Imperative Preloading
 
-You can also use the [`usePreloadRoute`](/solid-router/references/use-preload-route) helper to preload routes programmatically in response to events other than link hover/focus, such as button clicks or timers.
+You can also use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper to preload routes programmatically in response to events other than link hover/focus, such as button clicks or timers.
 This helper will load only the route's component by default, but it can receive a configuration object to also load the data.
 
 ## Preloading and Lazy Loading
 
-When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/references/use-preload-route) helper in the parent component to load them when needed.
\ No newline at end of file
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
\ No newline at end of file

From f364e3294510e180a96d6ec977e09f42ed48e1fd Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 18:37:31 +0200
Subject: [PATCH 04/14] "start" fetching data

---
 src/routes/solid-router/advanced-concepts/preloading.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index 46e52906d2..c10262c374 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -5,7 +5,7 @@ title: Preloading
 When using the [`<A>`](/solid-router/reference/components/a) component from Solid Router, routes are preloaded by default on link hover/focus to improve perceived performance.
 
 To enhance preloading, you can define the `preload` function on your route definition.
-When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to fetch data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
+When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to start fetching data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
 
 | user action | route behavior                          |
 | ----------- | -------------------------------------- |

From a4c79c1275a8163a1e730e42ea21e67a65f540d0 Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sat, 18 Oct 2025 19:42:46 +0200
Subject: [PATCH 05/14] both `<A>` and `<a>` have the preload behavior, remove
 ambiguous sentence

---
 src/routes/solid-router/advanced-concepts/preloading.mdx        | 2 +-
 .../solid-router/reference/primitives/use-preload-route.mdx     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index c10262c374..b14cd5b107 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -2,7 +2,7 @@
 title: Preloading
 ---
 
-When using the [`<A>`](/solid-router/reference/components/a) component from Solid Router, routes are preloaded by default on link hover/focus to improve perceived performance.
+Anchors in Solid Router will preload routes by default on link hover/focus to improve perceived performance.
 
 To enhance preloading, you can define the `preload` function on your route definition.
 When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to start fetching data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
diff --git a/src/routes/solid-router/reference/primitives/use-preload-route.mdx b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
index cd7d880ec3..90d843b44d 100644
--- a/src/routes/solid-router/reference/primitives/use-preload-route.mdx
+++ b/src/routes/solid-router/reference/primitives/use-preload-route.mdx
@@ -12,7 +12,7 @@ preload(`/users/settings`, { preloadData: true });
 
 ## Usage
 
-Routes are preloaded by default when using the [`<A>`](/solid-router/reference/components/a) component.
+Routes are preloaded by default within Solid Router contexts.
 This helper is useful when you want to preload a route in response to some other event, such as a button click or a timer.
 
 ## Type Signature

From 7937b09f0c7b60b24e8671483d0d613770d276be Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sun, 19 Oct 2025 18:38:40 +0200
Subject: [PATCH 06/14] more content on lazy loading and nested components

---
 src/routes/reference/component-apis/lazy.mdx  | 73 ++++++++++++++++---
 .../advanced-concepts/preloading.mdx          |  4 +-
 2 files changed, 65 insertions(+), 12 deletions(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index d6b7144330..33a8362aa8 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -2,24 +2,75 @@
 title: lazy
 ---
 
-```ts
+Used to lazy load components to allow for code splitting. 
+Components are not loaded until rendered. 
+
+```tsx title="app.tsx"
+import { lazy } from "solid-js"
+
+const ComponentA = lazy(() => import("./ComponentA"));
+
+function App(props: { title: string }) {
+  return (
+		<ComponentA title={props.title} />
+	)
+}
+```
+
+Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. 
+Lazy components trigger `<Suspense>`
+
+## Preloading data in Nested Lazy Components
+
+Top-level lazy components will automatically be preloaded as well as their preload functions.
+Though nested lazy components will not be preloaded automatically because they are not part of the route hyerarchy.
+To preload such components, you can use the `preload` method exposed on the lazy component
+
+```tsx title="component-with-preload.tsx"
 import { lazy } from "solid-js"
 import type { Component } from "solid-js"
 
+const Nested = lazy(() => import("./Nested"))
+
+const ComponentWithPreload: Component = () => {
+  // preload Nested component when needed
+  async function handlePreload() {
+	await Nested.preload()
+  }
+
+  return (
+	<div>
+	  <button onClick={handlePreload}>Preload Nested Component</button>
+	  <Nested />
+	</div>
+  )
+}
+
+```
+
+## Type Signature
+
+```tsx
 function lazy<T extends Component<any>>(
 	fn: () => Promise<{ default: T }>
 ): T & { preload: () => Promise<T> }
 ```
 
-Used to lazy load components to allow for code splitting. 
-Components are not loaded until rendered. 
-Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. 
-Lazy components trigger `<Suspense>`
+### Type Parameters
 
-```tsx
-// wrap import
-const ComponentA = lazy(() => import("./ComponentA"));
+| Name | Constraint | Description |
+| ---- | ---------- | ----------- |
+| `T`  | `Component<any>` | The component type that will be lazily loaded (including its props).
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `fn` | `() => Promise<{ default: T }>` | Yes | A function that returns a dynamic import resolving to the component as the `default` export. |
+
+### Returns
+
+| Type | Description |
+| ---- | ----------- |
+| `T & { preload: () => Promise<T> }` | A renderable component compatible with `T` that also exposes a `preload()` method to eagerly load the module. |
 
-// use in JSX
-<ComponentA title={props.title} />
-```
diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index b14cd5b107..22ae307ac1 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -19,4 +19,6 @@ This helper will load only the route's component by default, but it can receive
 
 ## Preloading and Lazy Loading
 
-When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
\ No newline at end of file
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
+
+To learn more about lazy loading components, see the [`lazy`](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components) documentation.
\ No newline at end of file

From e64012883a2ac325105f30beb4c093c724f35c3b Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Mon, 20 Oct 2025 10:38:04 +0200
Subject: [PATCH 07/14] fix typo

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
---
 src/routes/reference/component-apis/lazy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index 33a8362aa8..306c24679b 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -23,7 +23,7 @@ Lazy components trigger `<Suspense>`
 ## Preloading data in Nested Lazy Components
 
 Top-level lazy components will automatically be preloaded as well as their preload functions.
-Though nested lazy components will not be preloaded automatically because they are not part of the route hyerarchy.
+Though nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
 To preload such components, you can use the `preload` method exposed on the lazy component
 
 ```tsx title="component-with-preload.tsx"

From b1a0fb0773cb6d4ccf316a4ae54cc61799e325c1 Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Thu, 23 Oct 2025 09:54:14 +0200
Subject: [PATCH 08/14] clarify sentence with manually preloading

Co-authored-by: Eric L. Goldstein <3359116+mangs@users.noreply.github.com>
---
 src/routes/reference/component-apis/lazy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index 306c24679b..ffd2146209 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -3,7 +3,7 @@ title: lazy
 ---
 
 Used to lazy load components to allow for code splitting. 
-Components are not loaded until rendered. 
+Components are not loaded until rendered or manually preloaded. 
 
 ```tsx title="app.tsx"
 import { lazy } from "solid-js"

From 4b4f2e382d9dc810e938c16ab154eb6d8de0e391 Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Thu, 23 Oct 2025 09:54:31 +0200
Subject: [PATCH 09/14] better English :)

Co-authored-by: Eric L. Goldstein <3359116+mangs@users.noreply.github.com>
---
 src/routes/reference/component-apis/lazy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index ffd2146209..d7d3d4d957 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -23,7 +23,7 @@ Lazy components trigger `<Suspense>`
 ## Preloading data in Nested Lazy Components
 
 Top-level lazy components will automatically be preloaded as well as their preload functions.
-Though nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
+However, nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
 To preload such components, you can use the `preload` method exposed on the lazy component
 
 ```tsx title="component-with-preload.tsx"

From 143ba25626ea02dc71d2cf56018ed9c3d600871a Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Thu, 23 Oct 2025 09:54:51 +0200
Subject: [PATCH 10/14] typo :)

Co-authored-by: Eric L. Goldstein <3359116+mangs@users.noreply.github.com>
---
 src/routes/reference/component-apis/lazy.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index d7d3d4d957..09babbc3a6 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -24,7 +24,7 @@ Lazy components trigger `<Suspense>`
 
 Top-level lazy components will automatically be preloaded as well as their preload functions.
 However, nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
-To preload such components, you can use the `preload` method exposed on the lazy component
+To preload such components, you can use the `preload` method exposed on the lazy component.
 
 ```tsx title="component-with-preload.tsx"
 import { lazy } from "solid-js"

From 4be0415189b42353baef6fc7793c6a7671a31a9b Mon Sep 17 00:00:00 2001
From: Atila Fassina <atila@fassina.eu>
Date: Sun, 26 Oct 2025 20:15:11 +0100
Subject: [PATCH 11/14] Update
 src/routes/solid-router/advanced-concepts/preloading.mdx

Co-authored-by: Eric L. Goldstein <3359116+mangs@users.noreply.github.com>
---
 src/routes/solid-router/advanced-concepts/preloading.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index 22ae307ac1..0934dda063 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -19,6 +19,6 @@ This helper will load only the route's component by default, but it can receive
 
 ## Preloading and Lazy Loading
 
-When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper in the parent component to load them when needed.
+When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the `preload()` function returned from calling the [`lazy()`](https://docs.solidjs.com/reference/component-apis/lazy) component API.
 
 To learn more about lazy loading components, see the [`lazy`](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components) documentation.
\ No newline at end of file

From 50941344a2d4b099d2bc6541de5ec44f2617628d Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <hello@sarahgerrard.me>
Date: Thu, 11 Dec 2025 20:09:35 +0000
Subject: [PATCH 12/14] update pages

---
 src/routes/reference/component-apis/lazy.mdx  | 89 ++++++++++---------
 .../advanced-concepts/preloading.mdx          | 46 +++++++---
 2 files changed, 79 insertions(+), 56 deletions(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index eba987616c..4ada7fa3bf 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -16,40 +16,66 @@ description: >-
   performance. Components load on-demand and integrate with Suspense.
 ---
 
-Used to lazy load components to allow for code splitting. 
-Components are not loaded until rendered or manually preloaded. 
+The `lazy` helper wraps a dynamic import and returns a component that loads on demand.
+Lazy components accept the same props as their eager counterparts and integrate with `<Suspense>` boundaries.
+
+## Import
+
+```tsx
+import { lazy } from "solid-js"
+```
+
+## Type
+
+```tsx
+function lazy<T extends Component<any>>(
+  fn: () => Promise<{ default: T }>
+): T & { preload: () => Promise<T> }
+```
+
+## Parameters
+
+### `fn`
+
+- **Type:** `() => Promise<{ default: T }>`
+- **Required:** Yes
+
+Dynamic import that resolves to the component module, exposing the component as the `default` export.
+
+## Return value
+
+`lazy` returns a renderable component compatible with `T`.
+The component exposes a `preload()` method that resolves the underlying module.
+
+| Property | Type | Description |
+| -------- | ---- | ----------- |
+| `preload` | `() => Promise<T>` | Loads the module without rendering and returns the resolved component. |
+
+## Examples
+
+### Basic usage
 
 ```tsx title="app.tsx"
 import { lazy } from "solid-js"
 
-const ComponentA = lazy(() => import("./ComponentA"));
+const ComponentA = lazy(() => import("./ComponentA"))
 
 function App(props: { title: string }) {
-  return (
-		<ComponentA title={props.title} />
-	)
+  return <ComponentA title={props.title} />
 }
 ```
 
-Lazy loaded components can be used the same as its statically imported counterpart, receiving props etc. 
-Lazy components trigger `<Suspense>`
-
-## Preloading data in Nested Lazy Components
-
-Top-level lazy components will automatically be preloaded as well as their preload functions.
-However, nested lazy components will not be preloaded automatically because they are not part of the route hierarchy.
-To preload such components, you can use the `preload` method exposed on the lazy component.
+### Preloading nested lazy components
 
-```tsx title="component-with-preload.tsx"
+```tsx
 import { lazy } from "solid-js"
 import type { Component } from "solid-js"
 
 const Nested = lazy(() => import("./Nested"))
 
 const ComponentWithPreload: Component = () => {
-  // preload Nested component when needed
   async function handlePreload() {
-	await Nested.preload()
+	  await Nested.preload()
   }
 
   return (
@@ -59,32 +85,9 @@ const ComponentWithPreload: Component = () => {
 	</div>
   )
 }
-
-```
-
-## Type Signature
-
-```tsx
-function lazy<T extends Component<any>>(
-	fn: () => Promise<{ default: T }>
-): T & { preload: () => Promise<T> }
 ```
 
-### Type Parameters
-
-| Name | Constraint | Description |
-| ---- | ---------- | ----------- |
-| `T`  | `Component<any>` | The component type that will be lazily loaded (including its props).
-
-### Parameters
-
-| Parameter | Type | Required | Description |
-| --------- | ---- | -------- | ----------- |
-| `fn` | `() => Promise<{ default: T }>` | Yes | A function that returns a dynamic import resolving to the component as the `default` export. |
-
-### Returns
-
-| Type | Description |
-| ---- | ----------- |
-| `T & { preload: () => Promise<T> }` | A renderable component compatible with `T` that also exposes a `preload()` method to eagerly load the module. |
+## See also
 
+- [`Suspense`](https://docs.solidjs.com/reference/component-apis/suspense)
+- [Router preloading guide](/solid-router/advanced-concepts/preloading)
diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index 0934dda063..9d762dd022 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -2,23 +2,43 @@
 title: Preloading
 ---
 
-Anchors in Solid Router will preload routes by default on link hover/focus to improve perceived performance.
+Preloading smooths navigation by resolving route code and data before a user completes a transition.
+Solid Router listens for intent signals, such as hover and focus, and primes the matching route after a short delay to balance responsiveness and network cost.
+Understanding the timing and scope of this work lets you decide when to rely on the default behaviour and when to layer custom strategies.
 
-To enhance preloading, you can define the `preload` function on your route definition.
-When on a [SolidStart](/solid-start) application, this function can also run on the server during the initial page load to start fetching data before rendering. When in a Single-Page Application (SPA), it will load the route's component and its `preload` function when the user hovers or focuses on a link.
+| user action | route behaviour |
+| ----------- | --------------- |
+| hover | waits roughly 20 ms before preloading |
+| focus | preloads immediately |
 
-| user action | route behavior                          |
-| ----------- | -------------------------------------- |
-| hover   | with a 300ms delay to avoid excessive preloading  |
-| focus   | immediately                           |
+## How Solid Router Detects Intent
 
-## Imperative Preloading
+Anchors registered with Solid Router emit hover and focus events that feed a small scheduler.
+The router debounces the hover signal for 20ms to ignore incidental pointer passes while still reacting quickly to purposeful movement.
+When the delay elapses, the router loads the route module and runs its preload routine so that navigation has the assets it needs when the user commits.
 
-You can also use the [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) helper to preload routes programmatically in response to events other than link hover/focus, such as button clicks or timers.
-This helper will load only the route's component by default, but it can receive a configuration object to also load the data.
+Route modules can export a [`preload`](/solid-router/reference/preload-functions/preload) function that receives params, search values, and router context.
+The function lets you seed caches, warm derived computations, or coordinate streaming behaviours without blocking the eventual render.
 
-## Preloading and Lazy Loading
+> [!NOTE]
+> [SolidStart](/solid-start) also invokes route `preload` functions during the initial server render and resumes them on the client during hydration.
+> Keep these functions pure so the hydrated client does not need to undo server work when it takes over.
 
-When a route has nested lazy components, such components will not be part of the route hierarchy, so they **will not** be preloaded with the route. To preload such components, you can use the `preload()` function returned from calling the [`lazy()`](https://docs.solidjs.com/reference/component-apis/lazy) component API.
+## Imperative Preloading Hooks
 
-To learn more about lazy loading components, see the [`lazy`](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components) documentation.
\ No newline at end of file
+Not every interaction funnels through an anchor element.
+The [`usePreloadRoute`](/solid-router/reference/primitives/use-preload-route) primitive exposes the same scheduling behaviour for imperative flows like flyout previews, timers, or observer driven experiences.
+
+This helper mirrors the router behaviour by resolving the module, optionally running the loader, and caching the result for the eventual navigation.
+Empirical tuning of delay values helps you avoid excessive prefetching in dense UIs while still keeping high intent interactions snappy.
+
+## Coordinating Nested Lazy Components
+
+Nested lazy components live outside the router hierarchy, so route preloading does not automatically warm them.
+The component API [`lazy()`](/reference/component-apis/lazy) exposes a `preload()` method that resolves a component without rendering it.
+Calling both the route preload and the nested component preload can keep large detail panels responsive when a user hovers or focuses on the entry point.
+
+Balancing manual preloading requires observing real user flows so you avoid prefetching large bundles that the user never requests.
+Profiling tools help you spot whether preloading reduces long tasks or simply shifts work earlier without net gains.
+
+To learn more about lazy loading components, see the [lazy documentation](/reference/component-apis/lazy#preloading-data-in-nested-lazy-components).

From b763734adbb25d43bf62add5fb4fb1a990d9e109 Mon Sep 17 00:00:00 2001
From: Sarah Gerrard <hello@sarahgerrard.me>
Date: Thu, 11 Dec 2025 20:11:03 +0000
Subject: [PATCH 13/14] fix example

---
 src/routes/reference/component-apis/lazy.mdx | 15 +++++++++------
 1 file changed, 9 insertions(+), 6 deletions(-)

diff --git a/src/routes/reference/component-apis/lazy.mdx b/src/routes/reference/component-apis/lazy.mdx
index 4ada7fa3bf..e9b76fa2ea 100644
--- a/src/routes/reference/component-apis/lazy.mdx
+++ b/src/routes/reference/component-apis/lazy.mdx
@@ -73,15 +73,18 @@ import type { Component } from "solid-js"
 
 const Nested = lazy(() => import("./Nested"))
 
-const ComponentWithPreload: Component = () => {
-  async function handlePreload() {
-	  await Nested.preload()
-  }
+const ComponentWithPreload = () => {
+  const [showNested, setShowNested] = createSignal(false)
 
   return (
 	<div>
-	  <button onClick={handlePreload}>Preload Nested Component</button>
-	  <Nested />
+	  <button
+        onMouseEnter={() => Nested.preload()}
+        onClick={() => setShowNested(true)}
+      >Preload Nested Component</button>
+      <Show when={showNested()}>
+	    <Nested />
+      </Show>
 	</div>
   )
 }

From c31ce54bc737710d9fc792baabe241d40e39b8bd Mon Sep 17 00:00:00 2001
From: Sarah <gerrardsarah@gmail.com>
Date: Tue, 16 Dec 2025 19:50:32 -0800
Subject: [PATCH 14/14] Update note on SSR and route preload functions

Clarified the note about SSR invoking route preload functions.
---
 src/routes/solid-router/advanced-concepts/preloading.mdx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/routes/solid-router/advanced-concepts/preloading.mdx b/src/routes/solid-router/advanced-concepts/preloading.mdx
index 9d762dd022..7adb4431f9 100644
--- a/src/routes/solid-router/advanced-concepts/preloading.mdx
+++ b/src/routes/solid-router/advanced-concepts/preloading.mdx
@@ -21,7 +21,7 @@ Route modules can export a [`preload`](/solid-router/reference/preload-functions
 The function lets you seed caches, warm derived computations, or coordinate streaming behaviours without blocking the eventual render.
 
 > [!NOTE]
-> [SolidStart](/solid-start) also invokes route `preload` functions during the initial server render and resumes them on the client during hydration.
+> SSR invokes route `preload` functions during the initial server render and resumes them on the client during hydration.
 > Keep these functions pure so the hydrated client does not need to undo server work when it takes over.
 
 ## Imperative Preloading Hooks