You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**auto_load_bundle:** will automatically load the bundle for component by calling `append_javascript_pack_tag` and `append_stylesheet_pack_tag` under the hood.
40
+
-**hydrate_on:** controls when React hydrates or client-renders this root. Supported OSS modes are `:immediate` (default), `:visible`, and `:idle`. See [Hydration Scheduling](../building-features/hydration-scheduling.md). `:interaction` is not supported. Deferred modes are OSS-only; React on Rails Pro currently accepts only `:immediate`.
39
41
-**id:** Id for the div, will be used to attach the React component. This will get assigned automatically if you do not provide an id. Must be unique.
40
42
-**html_options:** Any other HTML options get placed on the added div for the component. For example, you can set a class (or inline style) on the outer div so that it behaves like a span, with the styling of `display:inline-block`. You may also use an option of `tag: "span"` to replace the use of the default DIV tag to be a SPAN tag.
41
43
-**trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise. Only on the **client side** will you will see the `railsContext` and your props.
`hydrate_on` lets a Rails view keep server-rendered HTML visible immediately while deferring when React attaches event handlers and effects for that island.
4
+
5
+
Deferred modes are implemented by the open-source client renderer. If React on Rails Pro is installed, non-immediate modes raise an error instead of silently hydrating immediately.
|`:immediate`| Default. Hydrates or client-renders as soon as React on Rails processes the component. |
21
+
|`:visible`| Uses `IntersectionObserver` and hydrates when the component container enters the viewport, with a 200px margin. |
22
+
|`:idle`| Uses `requestIdleCallback` with a timeout, falling back to a short timer when the browser lacks idle callbacks. |
23
+
24
+
## When to Use It
25
+
26
+
Use `hydrate_on: :visible` for below-the-fold islands such as recommendations, comments, footers, or sidebar widgets. Use `hydrate_on: :idle` for low-priority islands that are visible but not needed for the first interaction.
27
+
28
+
Keep `:immediate` for navigation, forms, buttons, and anything the user may interact with right away.
29
+
30
+
## Server-Rendered Islands
31
+
32
+
With `prerender: true`, the user sees the server-rendered HTML immediately. React hydration waits for the selected mode:
33
+
34
+
```erb
35
+
<%= react_component("Reviews",
36
+
props: { product_id: @product.id },
37
+
prerender: true,
38
+
hydrate_on: :visible) %>
39
+
```
40
+
41
+
Because the HTML is already present, this works well for content that should be readable before it becomes interactive. Avoid making deferred islands look interactive before hydration. For example, render controls disabled until the component has hydrated, or keep immediate hydration for controls above the fold.
42
+
43
+
## Client-Only Roots
44
+
45
+
`hydrate_on` also schedules client-only roots:
46
+
47
+
```erb
48
+
<%= react_component("ClientOnlyChart",
49
+
props: @chart_props,
50
+
prerender: false,
51
+
hydrate_on: :idle) %>
52
+
```
53
+
54
+
For `prerender: false`, the container stays empty until React renders. Prefer server rendering when users should see meaningful content before hydration.
55
+
56
+
## Turbo and Turbolinks Cleanup
57
+
58
+
React on Rails cancels pending `:visible` observers and `:idle` callbacks during the same page-unload lifecycle it uses to unmount React roots on Turbo and Turbolinks navigation. If a user navigates away before a deferred island hydrates, the pending observer or callback is disconnected so the old page cannot hydrate after Turbo swaps the body.
59
+
60
+
## What This Does Not Do
61
+
62
+
`hydrate_on` does not defer JavaScript bundle fetching. If you use `auto_load_bundle: true`, the generated bundle is still loaded when the page loads; only the React root creation is scheduled. Deferred bundle fetch is a separate optimization.
63
+
64
+
`:interaction` is not supported in the open-source package. Passing `hydrate_on: :interaction` raises an error. Use `:immediate`, `:visible`, or `:idle`.
65
+
66
+
Renderer functions, the 3-argument functions that call `hydrateRoot` or `createRoot` themselves, own their own mounting behavior. `hydrate_on` applies to normal React component registrations that React on Rails mounts for you.
`hydrate_on` lets a Rails view keep server-rendered HTML visible immediately while deferring when React attaches event handlers and effects for that island.
5426
+
5427
+
Deferred modes are implemented by the open-source client renderer. If React on Rails Pro is installed, non-immediate modes raise an error instead of silently hydrating immediately.
| `:immediate` | Default. Hydrates or client-renders as soon as React on Rails processes the component. |
5443
+
| `:visible` | Uses `IntersectionObserver` and hydrates when the component container enters the viewport, with a 200px margin. |
5444
+
| `:idle` | Uses `requestIdleCallback` with a timeout, falling back to a short timer when the browser lacks idle callbacks. |
5445
+
5446
+
## When to Use It
5447
+
5448
+
Use `hydrate_on: :visible` for below-the-fold islands such as recommendations, comments, footers, or sidebar widgets. Use `hydrate_on: :idle` for low-priority islands that are visible but not needed for the first interaction.
5449
+
5450
+
Keep `:immediate` for navigation, forms, buttons, and anything the user may interact with right away.
5451
+
5452
+
## Server-Rendered Islands
5453
+
5454
+
With `prerender: true`, the user sees the server-rendered HTML immediately. React hydration waits for the selected mode:
5455
+
5456
+
```erb
5457
+
<%= react_component("Reviews",
5458
+
props: { product_id: @product.id },
5459
+
prerender: true,
5460
+
hydrate_on: :visible) %>
5461
+
```
5462
+
5463
+
Because the HTML is already present, this works well for content that should be readable before it becomes interactive. Avoid making deferred islands look interactive before hydration. For example, render controls disabled until the component has hydrated, or keep immediate hydration for controls above the fold.
5464
+
5465
+
## Client-Only Roots
5466
+
5467
+
`hydrate_on` also schedules client-only roots:
5468
+
5469
+
```erb
5470
+
<%= react_component("ClientOnlyChart",
5471
+
props: @chart_props,
5472
+
prerender: false,
5473
+
hydrate_on: :idle) %>
5474
+
```
5475
+
5476
+
For `prerender: false`, the container stays empty until React renders. Prefer server rendering when users should see meaningful content before hydration.
5477
+
5478
+
## Turbo and Turbolinks Cleanup
5479
+
5480
+
React on Rails cancels pending `:visible` observers and `:idle` callbacks during the same page-unload lifecycle it uses to unmount React roots on Turbo and Turbolinks navigation. If a user navigates away before a deferred island hydrates, the pending observer or callback is disconnected so the old page cannot hydrate after Turbo swaps the body.
5481
+
5482
+
## What This Does Not Do
5483
+
5484
+
`hydrate_on` does not defer JavaScript bundle fetching. If you use `auto_load_bundle: true`, the generated bundle is still loaded when the page loads; only the React root creation is scheduled. Deferred bundle fetch is a separate optimization.
5485
+
5486
+
`:interaction` is not supported in the open-source package. Passing `hydrate_on: :interaction` raises an error. Use `:immediate`, `:visible`, or `:idle`.
5487
+
5488
+
Renderer functions, the 3-argument functions that call `hydrateRoot` or `createRoot` themselves, own their own mounting behavior. `hydrate_on` applies to normal React component registrations that React on Rails mounts for you.
- **auto_load_bundle:** will automatically load the bundle for component by calling `append_javascript_pack_tag` and `append_stylesheet_pack_tag` under the hood.
16215
+
- **hydrate_on:** controls when React hydrates or client-renders this root. Supported OSS modes are `:immediate` (default), `:visible`, and `:idle`. See [Hydration Scheduling](../building-features/hydration-scheduling.md). `:interaction` is not supported. Deferred modes are OSS-only; React on Rails Pro currently accepts only `:immediate`.
16142
16216
- **id:** Id for the div, will be used to attach the React component. This will get assigned automatically if you do not provide an id. Must be unique.
16143
16217
- **html_options:** Any other HTML options get placed on the added div for the component. For example, you can set a class (or inline style) on the outer div so that it behaves like a span, with the styling of `display:inline-block`. You may also use an option of `tag: "span"` to replace the use of the default DIV tag to be a SPAN tag.
16144
16218
- **trace:** set to true to print additional debugging information in the browser. Defaults to true for development, off otherwise. Only on the **client side** will you will see the `railsContext` and your props.
0 commit comments