Using Panel UI¶
Skill version 2026.11.12 · 16,244 chars · 1,925 words · 4,164 estimated tokens
panel.ui requires Panel 1.10 or later; on 1.9.x pn.ui does not exist. Check pn.__version__ before writing pn.ui code, and upgrade Panel if it is older.
Build panel.ui apps: what differs from plain Panel, Page structure, layouts, and component gotchas. For palette, typography, fonts, icons, brand assets and chart colors, see Theming Panel UI; for converting an existing plain-Panel app, see Migrating to Panel UI.
Contents¶
- Lookup — where to find
panel.uidocumentation - Key Differences from Panel
- Page — incl. header / AppBar color
- Layouts
- Component Gotchas
Lookup¶
Use Panel's API reference for panel.ui: https://panel.holoviz.org/api/panel.ui.html. Component documentation uses the same https://panel.holoviz.org/reference/{section}/{Component}.html convention as the rest of Panel. Search https://panel.holoviz.org/search.html?q=<topic> when the component location is unclear.
Key Differences from Panel¶
- Import Panel once and reference components as
pn.ui.X. Do not import the implementation package directly, add it or"bokeh"topn.extension(), or setdesign='material'. - Use
pn.ui.Column/pn.ui.Rowinpanel.uiapps so the whole app reads from one namespace and every layout acceptssx. Nativepn.Column/pn.Rowstill work and need no migration in existing code. The one exception is the layout directly wrapping a tile/geo plot, which must be native until the tile plot renders blank bug is fixed. - Fall back to
pn.*whenever nopanel.uiequivalent exists. If an existing app already usespn.*layouts, keep them rather than migrating. Manypn.uinames are plain re-exports of the classic class (pn.ui.Number is pn.indicators.Number, likewisepn.ui.Tabulator,pn.ui.Markdown,pn.ui.PNG); others are distinct Material classes with different params (pn.ui.ChatInterface,pn.ui.LoadingSpinner,pn.ui.Progressusescolor, notbar_color). Checkpn.ui.X.__module__when it matters. - Use
pn.ui.Pageinstead ofpn.template.FastListTemplate. - Use new param names (
label,color,variant) not legacy aliases (name,button_type,button_style). - Params don't generalize across components — don't infer one from a sibling widget.
variant,colorandsizeeach exist on only some components, and the allowed values differ where they do. Check before writing:'variant' in pn.ui.X.param,pn.ui.X.param.variant.objects,sorted(pn.ui.X.param). The ones that actually bite are tabled in Troubleshooting. - Quick preview with
python app.py+.show()works the same as for standard Panel. For iterating, preferpanel serve app.py --dev --show(see Serving Workflow). - Widget from a Param: pick one widget with
pn.ui.<Widget>.from_param(obj.param.x), or generate a whole form withpn.ui.Param(obj, parameters=[...], widgets={"x": pn.ui.Select}), which builds Material widgets (pn.Parambuilds classic ones).pn.ui.panelandpn.ui.HoloViewslikewise generate Material widgets for a DynamicMap's key dimensions. The Param-type → widget mapping matches Panel's own defaults (Param pane reference):param.Boolean→Checkbox(usepn.ui.Switch.from_paramif you want a switch),param.DataFrame→Tabulator,param.Array→pn.ui.ArrayInput.
import param
import panel as pn
pn.extension(throttled=True)
class MyApp(pn.viewable.Viewer):
value = param.Integer(default=5, bounds=(0, 10))
def __init__(self, **params):
super().__init__(**params)
with pn.config.set(sizing_mode="stretch_width"):
self._slider = pn.ui.IntSlider.from_param(self.param.value, margin=(10, 20))
self._output = pn.ui.Column(self._display)
# Build the Page once here — __panel__ returns it unconditionally.
self._page = pn.ui.Page(
title="My App",
sidebar=[self._slider],
main=[self._output],
)
@param.depends("value")
def _display(self):
return f"Value: {self.value}"
def __panel__(self):
return self._page
Page¶
- For a flat script,
pn.extension(template="page")creates a globalPage(pn.state.template); add to it with.servable(target=...), where targets are"main"(default),"sidebar","header"and"contextbar". There is no"modal"; usepn.ui.Dialog. Don't also call.servable()on aPageyou built yourself. In aViewerapp build thePageexplicitly as below. - Title goes in
Page.title— don't repeat inmain. Page.sidebar,Page.main,Page.headerrequire lists — not bare components orlist(layout).- Don't add
ThemeToggle— built in. headeris a single toolbar row — buttons, indicators, nav links only.- Add
margin=10to outermainlayouts so they stand out from sidebar. - Only use a sidebar when there are multiple control widgets. For a single selector, use inline
RadioButtonGrouporSelectin the main area withpn.ui.Container— avoids wasting viewport on a near-empty sidebar. - Sidebar order: logo → description → widgets → docs.
- Page not rendering (no header/sidebar): gating the
Pageconstruction/return onif pn.state.served:inside__panel__is a bug: the guard is alwaysFalsethere, even underpanel serve, so you silently get the blank/fallback layout with no top bar.pn.state.servedchecks whether its immediate caller's module is the served script, and it is Panel that calls__panel__, not your module. Always build thePageonce in__init__(e.g.self._page = pn.ui.Page(...)) and return it unconditionally from__panel__(return self._page).pn.state.servedremains correct at module level of the served script (if pn.state.served: App().servable()) — see Troubleshooting.
# ✅ Lists
pn.ui.Page(sidebar=[widget1, widget2], main=[content])
# ❌ Bare component — fails silently
pn.ui.Page(sidebar=widget1, main=content)
Page header / AppBar color¶
The Page header is an MUI AppBar color="primary". If theme_config sets no
palette.primary.main, it falls back to a hardcoded blue (#0072b5) with a white title — which
clashes with a dark app. Either set palette.primary.main, or override the header directly via the
.header class (use this when you want the header a different color from the brand primary, e.g. a
dark panel tone):
pn.ui.Page(
sx={"& .header": {
"backgroundColor": "#14141b", # match the app's panel color
"backgroundImage": "none",
"boxShadow": "none",
}},
...
)
Layouts¶
- Prefer
pn.ui.Column/pn.ui.Rowfor plain stacking (tile plot exception). Set gaps throughsx; there is nospacingparam. pn.ui.Container(width_option="lg")clamps content max width — prevents wide-screen stretching.pn.ui.Gridwithsize=breakpoints for responsive multi-column layouts (notncols, not barexs/sm/md), andspacing=2or more. Nest items insideGrid(container=True). KPI cards:size={"xs": 6, "md": 3}. Side-by-side charts:size={"xs": 12, "md": 6}.size="grow"for auto-sized items.- Set
sizing_mode="stretch_width"on children insideGriditems so they fill the cell. - List layouts take positional args:
pn.ui.Paper(a, b), notpn.ui.Paper([a, b]).
# 2-column responsive layout
pn.ui.Grid(
pn.ui.Grid(left_card, size={"xs": 12, "md": 6}),
pn.ui.Grid(right_card, size={"xs": 12, "md": 6}),
container=True, spacing=2,
)
# Width-clamped page content
pn.ui.Container(pn.ui.Column(...), width_option="lg")
Centering in Page¶
The pn.ui.Page main area does not support CSS flexbox centering. Use margins instead:
- Horizontal: wrap content in
pn.ui.Container(width_option="sm")for narrow centered cards - Vertical: use integer tuple margins like
margin=(100, 0, 0, 0)for top spacing.margin="auto"andpn.Spacer()don't work for vertical centering in Page
pn.ui.Page(
main=[
pn.ui.Container(
pn.ui.Column(
pn.ui.Paper(content, sx={"p": 5}),
sizing_mode="stretch_width",
margin=(100, 0, 0, 0), # Push down from top
),
width_option="sm", # Center horizontally with narrow width
)
],
)
Component Gotchas¶
Spacing and Alignment¶
pn.layout.HSpacer()pushes items left/right in a Rowpn.layout.VSpacer()pushes items top/bottom in a Column- Always set
sizing_modeon components unless intentionally fixed-size; fixed default widths are why widgets "aren't responsive". - Use
marginto prevent widgets touching container edges (default margins often suffice). Default margins are inconsistent (most10;Typography(5,10);Chip/Avatar/containers0), so loose text/buttons won't align with margin-0Grid/Paperblocks — pick one baseline. - Align a whole body: make each section an item of ONE
Grid(container=True, spacing=2)with childrenmargin=0— shared padding aligns them andspacingmakes the gaps (also stops cards touching):
pn.ui.Grid(pn.ui.Grid(title, size={"xs": 12}),
pn.ui.Grid(card, size={"xs": 12, "sm": 6, "md": 3}), ...,
container=True, spacing=2, sizing_mode="stretch_width")
- Slider thumb hits the edge → add horizontal margin, e.g.
margin=(10, 20). - Mixed-height rows:
align="center"; set gaps withsx={"gap": "12px"}, not per-item margins.alignis a Panel parameter on the layout and defaults to"start"; it sets the flex alignment on the container, so it beatssx={"alignSelf": "center"}on the child. Reaching foralignSelffirst is the usual reason a short label still sits high against taller buttons.
Components¶
Card: preferPaper. Setcollapsible=Falseunless needed.AutocompleteInputoverSelectpast ~20 options — a longSelectis a scroll hunt — and it's the only single-select widget that stays empty forvalue=None(why that matters):
pn.ui.AutocompleteInput.from_param(
obj.param.city, placeholder="Type to search…",
restrict=True, # keeps free text out of a validated Selector
search_strategy="includes", # "wa" matches Yakima, not just names starting with it
min_characters=0, # show the full list on focus (default is 2)
)
pn.indicators.Number styles its title and value together. It takes one styles
dict for the whole component, so a mono face or alert colour meant for the value cascades
onto the label too — you get an orange monospace caption. For a KPI card, compose two
Typographies instead, which also lets the label use overline:
# WRONG: mono + colour leak onto the label
pn.indicators.Number(name="Cities over AQI 100", value=6, default_color="#ef6c00",
styles={"font-family": MONO})
# CORRECT: quiet label, loud value
pn.ui.Paper(pn.ui.Typography("Cities over AQI 100", variant="overline", sx={"color": SOFT}),
pn.ui.Typography("6", variant="kpi", sx={"color": "#ef6c00"}))
Also note Number.format is a Python format spec ("{value:,.0f}"), not numeral.js —
"{value:0,0}" looks plausible next to Bokeh's formatters and raises ValueError.
- Tabulator: use "materialize" theme, not "material".
- Box → Column, TextField → TextInput (neither exists).
- Chip: use label=, not object= (deprecated). Chips default to margin=10, which blows out tight stacked layouts — set margin=0 when packing several together. Translucent-pill look: sx={"color": c, "backgroundColor": f"{c}22"}.
- Accordion header text: the title renders as a Typography inside the summary, so a rule on .MuiAccordionSummary-root won't reach it. Target the content to restyle the label: sx={"& .MuiAccordionSummary-content *": {"fontSize": "13px", "color": "#6d5cff"}}.
- RadioButtonGroup/CheckButtonGroup are MUI ToggleButtonGroups, so they take no
variant (why, and the other params that surprise)
— only color, size, orientation, disabled, label, sx. In a sidebar go vertical,
and get borders from sx:
pn.ui.RadioButtonGroup.from_param(
obj.param.mode, orientation="vertical", color="primary", size="small",
sx={"& .MuiToggleButton-root": {"borderColor": "divider"}},
)
CheckBoxGroup/RadioBoxGroup differ again: no orientation and no size — they take
inline (False stacks, True runs horizontally). Stacked is right in a sidebar, inline
above a wide table. With any of these four, don't add your own Typography label alongside —
the widget renders its own label and you get the text twice.
- Button groups (RadioButtonGroup, CheckButtonGroup) follow the same .from_param() after-super() ordering rule as any widget — see panel/SKILL.md for why.
- Rating (and other icon widgets): stretch to fill their container under the default sizing_mode="stretch_width", rendering enormous. Inline Markdown/HTML labels next to an HSpacer in the same Row fail the other way — they collapse to near-zero width and wrap one character per line. Pin both with an explicit width plus sizing_mode="fixed":
# ❌ Rating fills the row (giant stars); the label wraps vertically
pn.Row(pn.pane.Markdown("**Rating:**"), pn.ui.Rating(end=5), pn.layout.HSpacer())
# ✅ pinned
pn.Row(
pn.pane.HTML("<b>Rating:</b>", width=64, sizing_mode="fixed"),
pn.ui.Rating(end=5, size="small", width=170, sizing_mode="fixed"),
pn.layout.HSpacer(),
)
Dialog: for secondary detail that would crowd the page (or overflow the narrow Page contextbar), use a dialog and toggle .open. close_on_click=True dismisses on backdrop click:
self._details = pn.ui.Dialog(content, title="Details",
width_option="md", open=False, close_on_click=True)
# open from a button: self._details.open = True
Notifications¶
Toast-style alerts that float over the page rather than living in a fixed layout slot — the right choice for transient feedback ("saved", "request failed") where an inline Alert would shift layout. Enable once with pn.extension(notifications=True) (or pn.config.notifications = True), then call from any callback:
pn.state.notifications.success("Saved", duration=3000)
pn.state.notifications.error("Request failed", duration=0) # duration=0 stays until dismissed
pn.state.notifications.info("...")
pn.state.notifications.warning("...")
pn.state.notifications.send("Custom", background="#ff0000", icon="local_fire_department")
pn.state.notifications.clear()
The API is identical in plain Panel and panel.ui — no separate panel.ui import needed, and pn.state.notifications.position = "top-right" controls placement.
Gotcha — threading: under pn.extension(nthreads=...), calling a pn.state.notifications.* method from code running on a worker thread can silently stop executing the rest of that callback with no error surfaced (server and other callbacks keep running; only that one callback goes dark). If a callback that fires a notification stops having its later side effects apply once threading is enabled, this is the first thing to suspect — move the notification call off the threaded path, or verify the specific call actually completes.