Textualize/textual · error · StyleValueError

invalid value for display (received {new_val!r}, expected {f

Error message

invalid value for display (received {new_val!r}, expected {friendly_list(VALID_DISPLAY)})

What it means

The display setter accepts booleans or one of the valid CSS display keywords; anything else raises StyleValueError. Valid values come from VALID_DISPLAY (e.g. 'block', 'none').

Source

Thrown at src/textual/dom.py:933

        )

    @display.setter
    def display(self, new_val: bool | str) -> None:
        """
        Args:
            new_val: Shortcut to set the ``display`` CSS property.
                ``False`` will set ``display: none``. ``True`` will set ``display: block``.
                A ``False`` value will prevent the DOMNode from consuming space in the layout.
        """
        # TODO: This will forget what the original "display" value was, so if a user
        #  toggles to False then True, we'll reset to the default "block", rather than
        #  what the user initially specified.
        if isinstance(new_val, bool):
            self.styles.display = "block" if new_val else "none"
        elif new_val in VALID_DISPLAY:
            self.styles.display = new_val
        else:
            raise StyleValueError(
                f"invalid value for display (received {new_val!r}, "
                f"expected {friendly_list(VALID_DISPLAY)})",
            )

    @property
    def visible(self) -> bool:
        """Is this widget visible in the DOM?

        If a widget hasn't had its visibility set explicitly, then it inherits it from its
        DOM ancestors.

        This may be set explicitly to override inherited values.
        The valid values include the valid values for the `visibility` rule and the booleans
        `True` or `False`, to set the widget to be visible or invisible, respectively.

        When a node is invisible, Textual will reserve space for it, but won't display anything.
        """
        own_value = self.styles.get_rule("visibility")

View on GitHub (pinned to 06dbeef4bb)

Solutions

1. Use a boolean (True -> 'block', False -> 'none') or one of the documented VALID_DISPLAY strings
2. Check VALID_DISPLAY from textual.css.constants before assigning dynamic values
3. Use widget.styles.display only with supported keywords, or hide/show via widget.visible for visibility semantics

Example fix

# before
widget.display = 'inline-block'  # StyleValueError

# after
widget.display = False  # or 'none' / 'block'

from textual.css.constants import VALID_DISPLAY

def set_display(widget, value):
    if isinstance(value, bool) or value in VALID_DISPLAY:
        widget.display = value
    else:
        raise ValueError(f'unsupported display {value!r}')

from textual.css.constants import VALID_DISPLAY
def is_valid_display(v) -> bool:
    return isinstance(v, bool) or (isinstance(v, str) and v in VALID_DISPLAY)

from textual.css.styles import StylesError  # StyleValueError base
try:
    widget.display = value
except StylesError:
    widget.display = 'block'  # safe fallback

When it happens

Trigger: Assigning widget.display = 'inline-block' or another unsupported keyword, or a non-str/non-bool value like an int or None.

Common situations: Assuming full CSS display support (textual supports only a subset); passing a computed value that can be None or 0; version differences where supported display values changed.

Related errors

• invalid value for visibility (received {new_value!r}, expect
• {self.name} must be a str (e.g. '10%') or a float (e.g. 0.1)
• Expected a character or hatch value here; found {character!r
• {token!r} is not a valid scalar
• KeyError(key)

AI-assisted analysis of Textualize/textual@06dbeef4bb (2026-08-27). Data as JSON: /api/errors/6b53beba8294f487. Report an issue: GitHub.