TickerItem¶

An individual entry in a Marquee ticker, displaying a symbol, value, and optional change indicator.

Basic Usage¶

from pywry import TickerItem

item = TickerItem(
    symbol="AAPL",
    value="$185.32",
    change="+1.2%",
)

Properties¶

Property	Description	Example
`symbol`	Identifier/label	"AAPL", "BTC", "📈"
`value`	Current value	"$185.32", "12,453"
`change`	Change indicator	"+1.2%", "-5.3%", ""

Change Styling¶

The change value automatically styles based on prefix:

# Positive (green styling)
TickerItem(symbol="AAPL", value="$185", change="+1.2%")

# Negative (red styling)
TickerItem(symbol="GOOGL", value="$141", change="-0.5%")

# Neutral (no color)
TickerItem(symbol="INFO", value="Status", change="")

Common Patterns¶

Stock Quote¶

TickerItem(
    symbol="AAPL",
    value="$185.32",
    change="+2.15 (+1.17%)",
)

Cryptocurrency¶

TickerItem(
    symbol="BTC",
    value="$67,234",
    change="+3.2%",
)

Metrics¶

[
    TickerItem(symbol="Users", value="12,453", change="+5%"),
    TickerItem(symbol="Revenue", value="$1.2M", change="+12%"),
    TickerItem(symbol="CPU", value="45%", change=""),
    TickerItem(symbol="Memory", value="8.2GB", change=""),
]

With Icons¶

[
    TickerItem(symbol="📈", value="S&P 500", change="+0.8%"),
    TickerItem(symbol="💰", value="Gold", change="-0.3%"),
    TickerItem(symbol="⛽", value="Oil", change="+1.5%"),
]

Building from Data¶

prices = [
    {"symbol": "AAPL", "price": 185.32, "change_pct": 1.2},
    {"symbol": "GOOGL", "price": 141.80, "change_pct": -0.5},
]

items = [
    TickerItem(
        symbol=p["symbol"],
        value=f"${p['price']:.2f}",
        change=f"{'+' if p['change_pct'] >= 0 else ''}{p['change_pct']:.1f}%",
    )
    for p in prices
]

ticker = Marquee(items=items)

Marquee - Container that displays scrolling TickerItems

API Reference¶

Bases: BaseModel

A single updatable item within a Marquee (e.g., stock price, metric).

This is a lightweight helper for creating spans with data-ticker attributes that can be individually updated via toolbar:marquee-set-item events. Since marquee content is duplicated for seamless scrolling, updates target ALL matching data-ticker elements.

NOT a full ToolbarItem - this is a content helper for use inside Marquee.

Attributes:

Name	Type	Description
`ticker`	`str`	Unique identifier for this item (e.g., "AAPL", "BTC", "cpu-usage"). Used as `data-ticker` attribute for targeting updates.
`text`	`str`	Initial text content to display.
`html`	`str`	Initial HTML content (alternative to text for rich content).
`class_name`	`str`	Additional CSS classes for styling.
`style`	`str`	Inline CSS styles.

Examples:

Create ticker items for a stock marquee:

>>> items = [
...     TickerItem(ticker="AAPL", text="AAPL $185.50", class_name="stock-up"),
...     TickerItem(ticker="GOOGL", text="GOOGL $142.20"),
...     TickerItem(ticker="MSFT", text="MSFT $415.80", class_name="stock-down"),
... ]
>>> marquee = Marquee(
...     text=" • ".join(item.build_html() for item in items),
...     speed=20,
... )

Update individual prices:

>>> event, data = items[0].update_payload(
...     text="AAPL $186.25", class_add="stock-up", class_remove="stock-down"
... )
>>> widget.emit(event, data)

build_html ¶

build_html() -> str

Build HTML span with data-ticker attribute.

Returns:

Type	Description
`str`	HTML span element with data-ticker for update targeting.

update_payload ¶

update_payload(text: str | None = None, html_content: str | None = None, styles: dict[str, str] | None = None, class_add: str | list[str] | None = None, class_remove: str | list[str] | None = None) -> tuple[str, dict[str, Any]]

Generate event name and payload for dynamic item updates.

Use with widget.emit() to update this ticker item's content/styles. Updates ALL elements matching this ticker (handles duplicated marquee content).

Parameters:

Name	Type	Description	Default
`text`	`str \| None`	New plain text content.	`None`
`html_content`	`str \| None`	New HTML content (use instead of text for rich content).	`None`
`styles`	`dict[str, str] \| None`	CSS styles to apply (e.g., {"color": "green", "fontWeight": "bold"}).	`None`
`class_add`	`str \| list[str] \| None`	CSS class(es) to add.	`None`
`class_remove`	`str \| list[str] \| None`	CSS class(es) to remove.	`None`