caddis-plugin: Instructions file for GitHub Copilot

Plotly Chart Guidelines

Best practices for creating Plotly charts in Streamlit applications.

Critical: Avoiding "undefined" Labels

The Problem

When passing title=None or an empty/whitespace title directly to Plotly Express functions (px.pie(), px.bar(), px.line(), etc.), some browsers/versions may render "undefined" as the chart title.

# ❌ BAD: Passing None or empty title to px functions can show "undefined"
fig = px.pie(
    data,
    names="category",
    values="count",
    title=None,  # May render as "undefined" in some browsers
)

# ❌ BAD: Passing title=chart_title where chart_title might be None
chart_title = title if title else None
fig = px.bar(data, x="x", y="y", title=chart_title)  # Risky!

The Solution

Never pass the title parameter to Plotly Express functions. Instead, set the title explicitly in fig.update_layout() using an empty string when no title is desired:

# ✅ GOOD: Don't pass title to px, set it in update_layout
chart_title = title if title and title.strip() else None

fig = px.pie(
    data,
    names="category",
    values="count",
    # NO title parameter here!
)

# Explicitly set title - use empty string for no title
fig.update_layout(
    title=chart_title if chart_title else "",
    height=300,
)

Complete Pattern

def render_my_chart(
    data: pd.DataFrame,
    title: str | None = None,
    height: int = 300,
) -> None:
    """Render a chart with proper title handling."""
    if data.empty:
        st.info("No data available")
        return

    # Determine if we have a valid title
    chart_title = title if title and title.strip() else None

    # Create figure WITHOUT title parameter
    fig = px.bar(
        data,
        x="category",
        y="value",
        color="category",
        # DO NOT include title here
    )

    # Apply layout with explicit title handling
    fig.update_layout(
        height=height,
        showlegend=False,
        title=chart_title if chart_title else "",  # Empty string, not None!
    )

    st.plotly_chart(fig, use_container_width=True)