Skip to content


The layer property is used to assign widgets to a layer. The value of the layer property must be the name of a layer defined using a layers declaration. Layers control the order in which widgets are painted on screen. More information on layers can be found in the guide.


layer: <STRING>;


In the example below, #box1 is yielded before #box2. However, since #box1 is on the higher layer, it is drawn on top of #box2.

LayersExample box1 (layer = above) box2 (layer = below)

from import App, ComposeResult
from textual.widgets import Static

class LayersExample(App):
    CSS_PATH = "layers.css"

    def compose(self) -> ComposeResult:
        yield Static("box1 (layer = above)", id="box1")
        yield Static("box2 (layer = below)", id="box2")

if __name__ == "__main__":
    app = LayersExample()
Screen {
    align: center middle;
    layers: below above;

Static {
    width: 28;
    height: 8;
    color: auto;
    content-align: center middle;

#box1 {
    background: darkcyan;
    layer: above;

#box2 {
    layer: below;
    background: orange;
    offset: 12 6;


/* Draw the widget on the layer called 'below' */
layer: below;


# Draw the widget on the layer called 'below'
widget.layer = "below"