diff --git a/src/content/docs/en/reference/directives-reference.mdx b/src/content/docs/en/reference/directives-reference.mdx
index 7a41013eaf714..d1d557b378371 100644
--- a/src/content/docs/en/reference/directives-reference.mdx
+++ b/src/content/docs/en/reference/directives-reference.mdx
@@ -133,6 +133,19 @@ Load and hydrate the component JavaScript once the page is done with its initial
 ```astro
 <ShowHideButton client:idle />
 ```
+
+### `timeout`
+
+<p><Since v="4.15.0" /></p>
+
+The maximum time to wait, in milliseconds, before hydrating the component, even if the page is not yet done with its initial load.
+
+This allows you to pass a value for [the `timeout` option from the `requestIdleCallback()` specification](https://www.w3.org/TR/requestidlecallback/#the-requestidlecallback-method). This means you can delay hydration for lower-priority UI elements with more control to ensure your element is interactive within a specified time frame.
+
+```astro
+<ShowHideButton client:idle={{timeout: 500}} />
+```
+
 ### `client:visible`
 
 - **Priority:** Low