Skip to content

Placeholder

Added in version 0.6.0

A widget that is meant to have no complex functionality. Use the placeholder widget when studying the layout of your app before having to develop your custom widgets.

The placeholder widget has variants that display different bits of useful information. Clicking a placeholder will cycle through its variants.

  • Focusable
  • Container

Example

The example below shows each placeholder variant.

PlaceholderApp Placeholder p2 here! This is a custom label for p1. #p4 #p3#p5Placeholde r Lorem ipsum dolor sit  26 x 6amet, consectetur 27 x 6 adipiscing elit. Etiam  feugiat ac elit sit amet  Lorem ipsum dolor sit amet,  consectetur adipiscing elit. Etiam 40 x 6 feugiat ac elit sit amet accumsan.  Suspendisse bibendum nec libero quis  gravida. Phasellus id eleifend ligula. Nullam imperdiet sem tellus, sed  vehicula nisl faucibus sit amet. Lorem ipsum dolor sit amet,  Praesent iaculis tempor ultricies. Sedconsectetur adipiscing elit. Etiam  lacinia, tellus id rutrum lacinia, feugiat ac elit sit amet accumsan.  sapien sapien congue mauris, sit amet Suspendisse bibendum nec libero quis 

from textual.app import App, ComposeResult
from textual.containers import Container, Horizontal, VerticalScroll
from textual.widgets import Placeholder


class PlaceholderApp(App):
    CSS_PATH = "placeholder.css"

    def compose(self) -> ComposeResult:
        yield VerticalScroll(
            Container(
                Placeholder("This is a custom label for p1.", id="p1"),
                Placeholder("Placeholder p2 here!", id="p2"),
                Placeholder(id="p3"),
                Placeholder(id="p4"),
                Placeholder(id="p5"),
                Placeholder(),
                Horizontal(
                    Placeholder(variant="size", id="col1"),
                    Placeholder(variant="text", id="col2"),
                    Placeholder(variant="size", id="col3"),
                    id="c1",
                ),
                id="bot",
            ),
            Container(
                Placeholder(variant="text", id="left"),
                Placeholder(variant="size", id="topright"),
                Placeholder(variant="text", id="botright"),
                id="top",
            ),
            id="content",
        )


if __name__ == "__main__":
    app = PlaceholderApp()
    app.run()
Placeholder {
    height: 100%;
}

#top {
    height: 50%;
    width: 100%;
    layout: grid;
    grid-size: 2 2;
}

#left {
    row-span: 2;
}

#bot {
    height: 50%;
    width: 100%;
    layout: grid;
    grid-size: 8 8;
}

#c1 {
    row-span: 4;
    column-span: 8;
    height: 100%;
}

#col1, #col2, #col3 {
    width: 1fr;
}

#p1 {
    row-span: 4;
    column-span: 4;
}

#p2 {
    row-span: 2;
    column-span: 4;
}

#p3 {
    row-span: 2;
    column-span: 2;
}

#p4 {
    row-span: 1;
    column-span: 2;
}

Reactive Attributes

Name Type Default Description
variant str "default" Styling variant. One of default, size, text.

Messages

This widget sends no messages.


textual.widgets.Placeholder class

def __init__(
    self,
    label=None,
    variant="default",
    *,
    name=None,
    id=None,
    classes=None
):

Bases: Widget

A simple placeholder widget to use before you build your custom widgets.

This placeholder has a couple of variants that show different data. Clicking the placeholder cycles through the available variants, but a placeholder can also be initialised in a specific variant.

The variants available are:

Variant Placeholder shows
default Identifier label or the ID of the placeholder.
size Size of the placeholder.
text Lorem Ipsum text.
Parameters
Name Type Description Default
label str | None

The label to identify the placeholder. If no label is present, uses the placeholder ID instead.

None
variant PlaceholderVariant

The variant of the placeholder.

'default'
name str | None

The name of the placeholder.

None
id str | None

The ID of the placeholder in the DOM.

None
classes str | None

A space separated string with the CSS classes of the placeholder, if any.

None

variant class-attribute instance-attribute

variant: Reactive[
    PlaceholderVariant
] = self.validate_variant(variant)

The current variant of the placeholder.

cycle_variant method

def cycle_variant(self):

Get the next variant in the cycle.

Returns
Type Description
Self

The Placeholder instance.

on_mount method

def on_mount(self):

Set the color for this placeholder.

render method

def render(self):

Render the placeholder.

Returns
Type Description
RenderableType

The value to render.

validate_variant method

def validate_variant(self, variant):

Validate the variant to which the placeholder was set.