pip install panel watchfiles hvplot hvsampledata

undefined

def __init__(self, **params):
    super().__init__(**params)

    # DO use sizing_mode="stretch_width" for components unless "fixed" or other sizing_mode is specifically needed
    with pn.config.set(sizing_mode="stretch_width"):
        # DO create widgets using `.from_param` method
        self._characters_input = pn.widgets.IntSlider.from_param(self.param.characters, margin=(10,20))

        # DO Collect input widgets into horizontal, columnar layout unless other layout is specifically needed
        self._inputs = pn.Column(self._characters_input, max_width=300)

        # CRITICAL: Create panes ONCE with reactive content
        # DON'T recreate panes and layouts in @param.depends methods - causes flickering!
        # DO bind reactive methods/functions to panes for smooth updates
        self._output_pane = pn.pane.Markdown(
            self.model,  # Reactive method reference
            sizing_mode="stretch_width"
        )

        # DO collect output components into some layout like Column, Row, FlexBox or Grid depending on use case
        self._outputs = pn.Column(self._output_pane)

        # DO collect all of your components into a combined layout useful for displaying in notebooks etc.
        self._panel = pn.Row(self._inputs, self._outputs)

# DO use caching to speed up bound methods that are expensive to compute or load data and return the same result for a given state of the class.
# DO add a ttl (time to live argument) for expensive data loading that changes over time.
@pn.cache(max_items=3)
# DO prefer .depends over .bind over .rx for reactivity methods on Parameterized classes as it can be typed and documented
# DON'T use `watch=True` or `.watch(...)` methods to update UI components directly.
# DO use `watch=True` or `.watch(...)` for updating the state parameters or triggering side effects like saving files or sending email.
@param.depends("characters")
def model(self):
    # CRITICAL: Return ONLY the content, NOT the layout/pane
    # The pane was created once in __init__, this just updates its content
    return transform(text, self.characters)

# DO use `watch=True` or `.watch(...)` for updating the state parameters or triggering side effects like saving files or sending email.
@param.depends("characters", watch=True)
def _inform_user(self):
    print(f"User selected to show {self.characters} characters.")

# DO provide a method for displaying the component in a notebook setting, i.e. without using a Template or other element that cannot be displayed in a notebook setting.
def __panel__(self):
    return self._panel

# DO provide a method to create a .servable app
@classmethod
def create_app(cls, **params):
    instance = cls(**params)
    # DO use a Template or similar page layout for served apps
    template = pn.template.FastListTemplate(
        # DO provide a title for the app
        title="Hello World App",
        # DO provide optional image, optional app description, optional navigation menu, input widgets, optional documentation and optional links in the sidebar
        # DO provide as list of components or a list of single horizontal layout like Column as the sidebar by default is 300 px wide
        sidebar=[instance._inputs],
        # DO provide a list of layouts and output components in the main area of the app.
        # DO use Grid or FlexBox layouts for complex dashboard layouts instead of combination Rows and Columns.
        main=[instance._outputs],
        # DO set main_layout=None for modern layout
        main_layout=None,
    )
    return template

DO serve the app with

```bash
panel serve path_to_this_file.py --show --dev

undefined

DO run the tests with:

```bash
pytest tests/path/to/test_file.py

undefined

undefined

undefined

chart = param.Parameter()

def __init__(self, **params):
    super().__init__(**params)

    # 1. Create static panes with reactive content
    self._summary_pane = pn.pane.Markdown(self._summary_text)
    self._chart_pane = pn.pane.HoloViews(self.param.chart)

    # 2. Create static layout structure
    self._layout = pn.Column(
        "# Dashboard",    # Static title
        self._summary_pane,  # Reactive content
        self._chart_pane,    # Reactive content
    )

# ✅ Good: Reactive content method
# Will be run multiple times when filter_value updates if multiple panes or reactive functions depend on the _summary_text method
@param.depends("filter_value")
def _summary_text(self):
    # Returns string content only, NOT a pane
    return f"**Count**: {len(self._get_data())}"

# ✅ Good: Reactive update of chart parameter
# Will be run only one time when filter_value updates - even if multiple panes or reactive functions depend on the chart value
@param.depends("filter_value", watch=True, on_init=True)
def _update_chart(self):
    # updates the chart object only, NOT a pane
    self.chart = self._get_data().hvplot.bar()

def __panel__(self):
    return self._layout

@param.depends("filter_value")
def view(self):
    # DON'T recreate panes/layouts on every parameter change!
    return pn.Column(
        "# Dashboard",
        pn.pane.Markdown(f"**Count**: {len(self._get_data())}"),
        pn.pane.HoloViews(self._get_data().hvplot.bar()),
    )

**Why This Matters:**

- ✅ Smooth updates without layout reconstruction
- ✅ No flickering - seamless transitions
- ✅ Better performance - avoids unnecessary DOM updates
- ✅ Professional UX

**Key Rules:**

1. DO create main layout structure and panes ONCE in `__init__`
2. DO bind panes to reactive methods or parameters (DON'T recreate them)
3. Reactive methods should return CONTENT only (strings, plots, dataframes), NOT panes/layouts
4. Use `@param.depends` for reactive methods that update pane content

template = pn.template.FastListTemplate(
    title="Hello World App",
    sidebar=[instance._inputs],
    main=[instance._outputs],
    main_layout=None,
)

with pn.config.set(sizing_mode="stretch_width"):
    character_input = pn.widgets...
    output_pane = pn.pane....

undefined

DON'T add "bokeh". It's already loaded:

```python

undefined

undefined

undefined

undefined

undefined

undefined

def __init__(self, **params):
    super().__init__(**params)
    self._plot_pane = pn.pane.Matplotlib(self._create_plot)

@param.depends('value')
def _create_plot(self):
    return create_plot(self.value)  # Returns plot only, not pane

undefined

undefined

undefined

undefined

**Best Practices**:

- DO use matplotlib for publication-quality static plots
- DO close figures after rendering to prevent memory leaks: `plt.close(fig)`
- DO consider hvPlot or Plotly for interactive plots instead

def create_plot(self) -> go.Figure:
    fig = ...
    template = "plotly_dark" if pn.state.theme=="dark" else "plotly_white"
    fig.update_layout(
        template=template, # Change template to align with the theme
        paper_bgcolor='rgba(0,0,0,0)', # Change to transparent background to align with the app background
        plot_bgcolor='rgba(0,0,0,0)' # Change to transparent background to align with the app background
    )
    return fig

undefined

✅ **DO use ECharts native string formatters or static values**:
```python

**ECharts Formatter Template Syntax**:

- `{a}` - series name
- `{b}` - data name (category)
- `{c}` - data value
- `{d}` - percentage (for pie charts)
- `{value}` - axis value
- Supports prefix/suffix: `'{value}%'`, `'${value}'`, `'{value} units'`

If you need complex formatting logic, pre-process your data in Python before passing to ECharts rather than using formatters.

**Reactive Updates with replaceMerge**:

When updating ECharts dynamically (e.g., filtering data that changes the number of series), ECharts uses a **merge strategy** by default. This can cause old series to persist when series are removed.

✅ **DO use `replaceMerge` option** when series count can change:
```python

❌ **WITHOUT replaceMerge** - old series persist:
```python

Use `replaceMerge` for any chart where:

- Users can filter data (year selectors, category filters)
- The number of series changes dynamically
- Data is grouped by categories that may be added/removed

DO make sure the chart title does not overlap with the rest of the plot including legend.

start_date, end_date = self.date_range

undefined