Merge pull request #6156 from Textualize/scrollbar-visibility

scrollbar visibility rule

Author: willmcgugan

CHANGELOG.md

@@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## Unreleased
+
+### Added
+
+- Added scrollbar-visibility rule https://github.com/Textualize/textual/pull/6156
+
 ## [6.2.1] - 2025-10-01
 
 - Fix inability to copy text outside of an input/textarea when it was focused https://github.com/Textualize/textual/pull/6148

docs/examples/styles/scrollbar_visibility.py

@@ -0,0 +1,27 @@
+from textual.app import App
+from textual.containers import Horizontal, VerticalScroll
+from textual.widgets import Label
+
+TEXT = """I must not fear.
+Fear is the mind-killer.
+Fear is the little-death that brings total obliteration.
+I will face my fear.
+I will permit it to pass over me and through me.
+And when it has gone past, I will turn the inner eye to see its path.
+Where the fear has gone there will be nothing. Only I will remain.
+"""
+
+
+class ScrollbarApp(App):
+    CSS_PATH = "scrollbar_visibility.tcss"
+
+    def compose(self):
+        yield Horizontal(
+            VerticalScroll(Label(TEXT * 10), classes="left"),
+            VerticalScroll(Label(TEXT * 10), classes="right"),
+        )
+
+
+if __name__ == "__main__":
+    app = ScrollbarApp()
+    app.run()

docs/examples/styles/scrollbar_visibility.tcss

@@ -0,0 +1,11 @@
+VerticalScroll {
+    width: 1fr;
+}
+
+.left {
+    scrollbar-visibility: visible; # The default
+}
+
+.right {
+    scrollbar-visibility: hidden;
+}

docs/styles/scrollbar_visibility.md

@@ -0,0 +1,60 @@
+# Scrollbar-visibility
+
+The `scrollbar-visibility` is used to show or hide scrollbars.
+
+If scrollbars are hidden, the user may still scroll the container using the mouse wheel / keys / and gestures, but
+there will be no scrollbars shown.
+
+## Syntax
+
+--8<-- "docs/snippets/syntax_block_start.md"
+scrollbar-visibility: hidden | visible;
+--8<-- "docs/snippets/syntax_block_end.md"
+
+
+### Values
+
+| Value               | Description                                          |
+| ------------------- | ---------------------------------------------------- |
+| `hidden`            | The widget's scrollbars will be hidden.              |
+| `visible` (default) | The widget's scrollbars will be displayed as normal. |
+
+
+## Examples
+
+The following example contains two containers with the same text.
+The container on the right has its scrollbar hidden.
+
+=== "Output"
+
+    ```{.textual path="docs/examples/styles/scrollbar_visibility.py"}
+    ```
+
+=== "scrollbar_visibility.py"
+
+    ```py
+    --8<-- "docs/examples/styles/scrollbar_visibility.py"
+    ```
+
+=== "scrollbar_visibility.tcss"
+
+    ```css
+    --8<-- "docs/examples/styles/scrollbar_visibility.tcss"
+    ```
+
+
+## CSS
+
+```css
+scrollbar-visibility: visible;
+scrollbar-visibility: hidden;
+```
+
+
+
+## Python
+
+```py
+widget.styles.scrollbar_visibility = "visible";
+widget.styles.scrollbar_visibility = "hidden";
+```

mkdocs-nav.yml

@@ -136,6 +136,7 @@ nav:
               - "styles/scrollbar_colors/scrollbar_corner_color.md"
           - "styles/scrollbar_gutter.md"
           - "styles/scrollbar_size.md"
+          - "styles/scrollbar_visibility.md"
           - "styles/text_align.md"
           - "styles/text_opacity.md"
           - "styles/text_overflow.md"

src/textual/_compositor.py

@@ -694,7 +694,7 @@ def add_widget(
                     if (
                         widget.show_vertical_scrollbar
                         or widget.show_horizontal_scrollbar
-                    ):
+                    ) and styles.scrollbar_visibility == "visible":
                         for chrome_widget, chrome_region in widget._arrange_scrollbars(
                             container_region
                         ):

src/textual/css/_styles_builder.py

@@ -52,6 +52,7 @@
     VALID_OVERLAY,
     VALID_POSITION,
     VALID_SCROLLBAR_GUTTER,
+    VALID_SCROLLBAR_VISIBILITY,
     VALID_STYLE_FLAGS,
     VALID_TEXT_ALIGN,
     VALID_TEXT_OVERFLOW,
@@ -76,6 +77,7 @@
     Display,
     EdgeType,
     Overflow,
+    ScrollbarVisibility,
     TextOverflow,
     TextWrap,
     Visibility,
@@ -768,6 +770,13 @@ def process_color(self, name: str, tokens: list[Token]) -> None:
     process_scrollbar_background_hover = process_color
     process_scrollbar_background_active = process_color
 
+    def process_scrollbar_visibility(self, name: str, tokens: list[Token]) -> None:
+        """Process scrollbar visibility rules."""
+        self.styles._rules["scrollbar_visibility"] = cast(
+            ScrollbarVisibility,
+            self._process_enum(name, tokens, VALID_SCROLLBAR_VISIBILITY),
+        )
+
     process_link_color = process_color
     process_link_background = process_color
     process_link_color_hover = process_color

src/textual/css/constants.py

@@ -90,6 +90,7 @@
 VALID_TEXT_WRAP: Final = {"wrap", "nowrap"}
 VALID_TEXT_OVERFLOW: Final = {"clip", "fold", "ellipsis"}
 VALID_EXPAND: Final = {"greedy", "optimal"}
+VALID_SCROLLBAR_VISIBILITY: Final = {"visible", "hidden"}
 
 HATCHES: Final = {
     "left": "╲",

src/textual/css/styles.py

@@ -48,6 +48,7 @@
     VALID_OVERLAY,
     VALID_POSITION,
     VALID_SCROLLBAR_GUTTER,
+    VALID_SCROLLBAR_VISIBILITY,
     VALID_TEXT_ALIGN,
     VALID_TEXT_OVERFLOW,
     VALID_TEXT_WRAP,
@@ -153,11 +154,10 @@ class RulesMap(TypedDict, total=False):
     scrollbar_background: Color
     scrollbar_background_hover: Color
     scrollbar_background_active: Color
-
     scrollbar_gutter: ScrollbarGutter
-
     scrollbar_size_vertical: int
     scrollbar_size_horizontal: int
+    scrollbar_visibility: ScrollbarVisibility
 
     align_horizontal: AlignHorizontal
     align_vertical: AlignVertical
@@ -242,6 +242,7 @@ class StylesBase:
         "scrollbar_background",
         "scrollbar_background_hover",
         "scrollbar_background_active",
+        "scrollbar_visibility",
         "link_color",
         "link_background",
         "link_color_hover",
@@ -424,6 +425,10 @@ class StylesBase:
     """Set the width of the vertical scrollbar (measured in cells)."""
     scrollbar_size_horizontal = IntegerProperty(default=1, layout=True)
     """Set the height of the horizontal scrollbar (measured in cells)."""
+    scrollbar_visibility = StringEnumProperty(
+        VALID_SCROLLBAR_VISIBILITY, "visible", layout=True
+    )
+    """Sets the visibility of the scrollbar."""
 
     align_horizontal = StringEnumProperty(
         VALID_ALIGN_HORIZONTAL, "left", layout=True, refresh_children=True
@@ -1153,6 +1158,8 @@ def append_declaration(name: str, value: str) -> None:
                 append_declaration(
                     "scrollbar-size-vertical", str(self.scrollbar_size_vertical)
                 )
+        if "scrollbar_visibility" in rules:
+            append_declaration("scrollbar-visibility", self.scrollbar_visibility)
 
         if "box_sizing" in rules:
             append_declaration("box-sizing", self.box_sizing)

src/textual/css/types.py

@@ -44,6 +44,7 @@
 TextWrap = Literal["wrap", "nowrap"]
 TextOverflow = Literal["clip", "fold", "ellipsis"]
 Expand = Literal["greedy", "expand"]
+ScrollbarVisibility = Literal["visible", "hidden"]
 
 Specificity3 = Tuple[int, int, int]
 Specificity6 = Tuple[int, int, int, int, int, int]