Animating the background of a container doesn't propagate to children

[michaelala25]

Hey y'all, I'm attempting to animate the background of a container, of which all children have their background set to transparent. However, I'm getting some strange behaviour that I haven't been able to suss out - the children of the container don't seem to be animating properly.

In this first simple example, the child backgrounds don't animate at all:

from textual.app import App, ComposeResult
from textual.color import Color
from textual.containers import Vertical
from textual.widgets import Button, Static

class PingContainer(Vertical):
    DEFAULT_CSS = """
    PingContainer {
        height: auto;
        padding: 1 2;
    }
    """

    def ping(self) -> None:
        # Child backgrounds aren't animated
        highlight = Color.parse("rgb(60, 60, 60)")
        self.styles.background = highlight

        def _fade() -> None:
            self.styles.animate("background", "transparent", duration=1.0)

        self.set_timer(0.5, _fade)

class TestApp(App):
    DEFAULT_CSS = """
    Screen {
        background: rgb(20, 20, 20);
    }
    #controls {
        height: auto;
        padding: 1;
    }
    """

    def compose(self) -> ComposeResult:
        with Vertical(id="controls"):
            yield Button("Ping", id="btn-ping")
        yield PingContainer(
            Static("I am a child Static — my background should match parent."),
            id="target",
        )

    def on_button_pressed(self, event: Button.Pressed) -> None:
        if event.button.id == "btn-ping":
            self.query_one("#target", PingContainer).ping()

if __name__ == "__main__":
    TestApp().run()

I tried doing this with a "--ping" CSS class instead, which does seem to propagate the initial background change to the children, but the animation still doesn't work for the child backgrounds. With the following ping implementation, the child background remains stuck at the initial grey:

    DEFAULT_CSS = """
    PingContainer {
        height: auto;
        padding: 1 2;
    }
    PingContainer.--ping {
        background: rgb(60, 60, 60);
    }
    """

    def ping(self) -> None:
        self.add_class("--ping")

        def _fade() -> None:
            self.remove_class("--ping")
            self.styles.background = Color.parse("rgb(60, 60, 60)")
            self.styles.animate("background", "transparent", duration=1.0)

        self.set_timer(0.5, _fade)

Here's a video demonstrating the behaviour:

2026-03-01.01-42-18.webm

One thing that seems to reliably trigger a refresh of the stuck background colours is to:

1. Defocus my terminal (I'm viewing this in windows powershell) by clicking on another window
2. Refocus the terminal by clicking on it again
3. Hover my mouse over the child widget.

Only then does the background revert to transparent, making me wonder if this is less of a textual issue and more of a terminal issue. This also only seems to occur when I run this very specific app in a very specific setting - running a similar app in a tmux pane gives different, more sporadic behaviour (sometimes hover triggers the redraw, sometimes it doesn't).

I spent a few hours with claude adding debug logs throughout the textual source to see if I could learn anything. Eventually after I noticed this mouse hover behaviour, it gave me this summary:

Mouse hover triggers a repaint because Textual updates the hover state (pseudo-class :hover), which forces a full re-render of that widget with fresh background_colors.

This means the child's StylesCache (_cache) retains stale rendered strips from the animation. The animation correctly marks the child dirty and re-renders it, but the compositor's partial update isn't actually sending those pixels to the terminal. When you defocus/refocus + hover, the terminal forces a full redraw and the correct cached data finally gets displayed.

This is a terminal partial update issue — the escape sequences for the child's region are being sent but your terminal (PowerShell/Windows Terminal over WSL) isn't applying them. The full repaint triggered by hover uses different escape sequences that the terminal does process.

This explains everything:

• The logs prove the rendering data is correct
• The data is correct in memory after animation
• But the terminal never visually updates those specific cells
• A hover/focus event forces a codepath that the terminal DOES respect

This is almost certainly a bug in how Textual's partial screen updates interact with Windows Terminal over WSL.

Can't speak to the veracity of this of course, this was in a session with very minimal supervision.

[willmcgugan]

Animate opacity

[michaelala25]

Thanks for responding so quickly - I might need you to hold my hand here a bit more though if you're inclined.

When you say animate opacity what specifically are you referring to - the opacity of the widget itself (as in self.styles.opacity in the PingContainer)? If so, wouldn't that just make the whole thing disappear? That's indeed the behaviour I see (with the child widget retaining the old background before fading out):

2026-03-02.18-31-12.mp4

[TomJGooding]

I think possibly related to a regression in Textual 6.0.0. See #6235 and #6367 (comment)

[michaelala25]

Thanks for cross-referencing that, definitely seems related. Also seeing that behaviour you pointed out in #6367 in that example app, even with the changes from #6372