docs

Author: willmcgugan

CHANGELOG.md

@@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Added
 
-- Added a 'stream' layout, which is a lot like vertical but with fewer supported rules (which is why it is faster)
+- Added a 'stream' layout, which is a lot like vertical but with fewer supported rules (which is why it is faster), will remain undocumented for now. https://github.com/Textualize/textual/pull/6013
 
 ## [5.1.1] - 2025-07-21
 

src/textual/layouts/stream.py

@@ -13,7 +13,18 @@
 class StreamLayout(Layout):
     """A cut down version of the vertical layout.
 
-    Faster, but with fewer supported "features".
+    The stream layout is faster, but has a few limitations compared to the vertical layout.
+
+    - All widgets are the full width (as if their widget is `1fr`).
+    - All widgets have an effective height of `auto`.
+    - `max-height` is supported, but only if it is a units value, all other extrema rules are ignored.
+    - No absolute positioning.
+    - No overlay: screen.
+    - Layers are ignored.
+
+    The primary use of `layout: stream` is for a long list of widgets in a scrolling container, such as
+    what you might expect from a LLM chat-bot. The speed improvement will only be significant with a lot of
+    child widgets, so stick to vertical layouts unless you see any slowdown.
 
     """