From 272040c7143b725f94072c751d9e914f4fb04a43 Mon Sep 17 00:00:00 2001
From: Hemanth <hemanthd0916@gmail.com>
Date: Wed, 8 Jul 2026 12:18:10 +0530
Subject: [PATCH] Document the constrain style

---
 docs/styles/constrain.md | 58 ++++++++++++++++++++++++++++++++++++++++
 mkdocs-nav.yml           |  1 +
 2 files changed, 59 insertions(+)
 create mode 100644 docs/styles/constrain.md

diff --git a/docs/styles/constrain.md b/docs/styles/constrain.md
new file mode 100644
index 0000000000..b49e5b1a9c
--- /dev/null
+++ b/docs/styles/constrain.md
@@ -0,0 +1,58 @@
+# Constrain
+
+The `constrain` style prevents a widget from being scrolled off the edges of the screen.
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+constrain: <a href="#values">&lt;constrain&gt;</a> <a href="#values">&lt;constrain&gt;</a>;
+
+constrain-x: <a href="#values">&lt;constrain&gt;</a>;
+constrain-y: <a href="#values">&lt;constrain&gt;</a>;
+--8<-- "docs/snippets/syntax_block_end.md"
+
+The two values for `constrain` set the constrain behavior for the horizontal and vertical axes, respectively.
+
+To constrain a single axis, use `constrain-x` or `constrain-y`.
+
+### Values
+
+| Value               | Description                                                                 |
+|----------------------|-------------------------------------------------------------------------------|
+| `none` (default)     | No constrain applied.                                                        |
+| `inflect`            | If the widget would be cut off, flip it around to the opposite side.         |
+| `inside`             | Keep the widget within the visible area of the screen, moving it if required.|
+
+## Example
+
+TODO: add a runnable example (see `docs/examples/styles/offset.py` and `offset.tcss` for the pattern to follow).
+
+## CSS
+
+```css
+/* Keep the widget fully on screen along both axes */
+constrain: inside;
+
+/* Flip the widget to the opposite side if it would be cut off, on the x axis only */
+constrain-x: inflect;
+
+/* Keep the widget on screen along the y axis only */
+constrain-y: inside;
+```
+
+## Python
+
+```python
+# Keep the widget fully on screen along both axes
+widget.styles.constrain = ("inside", "inside")
+
+# Flip the widget to the opposite side if it would be cut off, on the x axis only
+widget.styles.constrain_x = "inflect"
+
+# Keep the widget on screen along the y axis only
+widget.styles.constrain_y = "inside"
+```
+
+## See also
+
+ - [`offset`](./offset.md) to move a widget from its default position.
diff --git a/mkdocs-nav.yml b/mkdocs-nav.yml
index 64c36db335..6444cd471c 100644
--- a/mkdocs-nav.yml
+++ b/mkdocs-nav.yml
@@ -90,6 +90,7 @@ nav:
           - "styles/border_title_style.md"
           - "styles/box_sizing.md"
           - "styles/color.md"
+          - "styles/constrain.md"
           - "styles/content_align.md"
           - "styles/display.md"
           - "styles/dock.md"