docs: altair component page by chendaniely · Pull Request #326 · posit-dev/py-shiny-site

chendaniely · 2025-11-26T03:26:06Z

Adds a new Altair output component page. I also added a reference in the Jupyter Widgets Concepts page to the altair output.
My goal for the components page is to provide an altair, jupyterchart, and shiny example for all the ones in the altair jupyterchart docs page.
Not all of the examples are reproduced, some are redundant (like the observe results) and others like the ipywidgets.link() aren't supported by shinywidgets

Relevant conversations:

Documentation references:

https://altair-viz.github.io/user_guide/interactions/jupyter_chart.html#selection-params
https://shiny.posit.co/py/docs/jupyter-widgets.html#user-input
TODO: having trouble with shiny -> JupyterChart updating. e.g., having a shiny radio button to change color from this example: https://altair-viz.github.io/user_guide/interactions/jupyter_chart.html#updating-charts

…art and jchart name and object

Copilot

Pull request overview

This PR adds comprehensive documentation for using Altair (Vega-Altair) interactive visualizations in Shiny for Python applications. The documentation includes both Express and Core syntax examples, along with three interactive variations demonstrating different selection types.

Key changes:

Added complete Altair component documentation page with detailed usage instructions
Provided example apps for both Express and Core syntax
Included three variation examples: hover point selection, brush (interval) selection, and legend point selection

Reviewed changes

Copilot reviewed 9 out of 10 changed files in this pull request and generated 12 comments.

Show a summary per file

File	Description
images/altair.png	Screenshot/preview image for the Altair component documentation
components/outputs/plot-altair/index.qmd	Main documentation page explaining Altair integration, API references, and usage details
components/outputs/plot-altair/app-express.py	Basic Express syntax example showing filtered bar chart
components/outputs/plot-altair/app-core.py	Basic Core syntax example showing filtered bar chart
components/outputs/plot-altair/app-variation-hover-point-express.py	Express example demonstrating IndexSelection with hover interactions
components/outputs/plot-altair/app-variation-hover-point-core.py	Core example demonstrating IndexSelection with hover interactions
components/outputs/plot-altair/app-variation-brush-express.py	Express example demonstrating IntervalSelection with brush interactions
components/outputs/plot-altair/app-variation-brush-core.py	Core example demonstrating IntervalSelection with brush interactions
components/outputs/plot-altair/app-variation-point-express.py	Express example demonstrating PointSelection with legend binding
components/outputs/plot-altair/app-variation-point-core.py	Core example demonstrating PointSelection with legend binding

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…l-brush-express.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…over-express.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…over-core.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…over-express.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

cpsievert · 2025-12-04T20:20:41Z

+:::{#relevant-functions}
+:::


Drop the output_plot/render_plot. Add output_widget

cpsievert · 2025-12-04T20:21:45Z

+:::{#example}
+:::


Would be nice if the code block had a lightning bolt to open in shinylive -- like the plotly component page does

cpsievert · 2025-12-04T20:23:35Z

 Some widgets have attributes that _contain_ observable traits.
 One practical example of this is the `selections` attribute of altair's `JupyterChart` class, which has an [observable `point` trait](https://altair-viz.github.io/user_guide/interactions/jupyter_chart.html#point-selections).

+For more information about Shiny, Alatir, and JupyterChart, see the [Altair components page](/components/outputs/plot-altair/index.qmd).


Maybe we should feature this more prominently (perhaps in a callout) at the bottom of the ## Get Started section?

cpsievert · 2025-12-04T20:24:35Z

@@ -0,0 +1,220 @@
+---
+title: Plot (Altair)
+sidebar: components


Altair doesn't seem to be showing up in the sidebar

cpsievert · 2025-12-04T20:28:03Z

+
+To make an Altair figure, we need to do the following steps:
+
+::: {.panel-tabset group="syntax"}


Suggested change

::: {.panel-tabset group="syntax"}

::: {.panel-tabset .shiny-mode-tabset group="shiny-app-mode"}

cpsievert · 2025-12-04T20:30:19Z

+::: {.panel-tabset group="syntax"}
+## Express
+
+1. Import the `render_altair()` functions from `shinywidgets`.


Suggested change

1. Import the `render_altair()` functions from `shinywidgets`.

1. Import `render_altair` from `shinywidgets`.

cpsievert · 2025-12-04T20:36:34Z

+2. Define a function where you want to create the figure.
+    - If your function calls reactive values, Shiny will update your figure whenever those values change, in a [reactive fashion](https://shiny.posit.co/py/docs/reactive-programming.html).
+    - Do not forget to return the plot object from your function.
+
+3. Decorate your plotting function with a `@render_altair()` decorator.
+    - If your plotting function is not the same as the `id` you used in the `ui.output_widget()`, you can add an additional `@output(id=...)` decorator.


Suggested change

2. Define a function where you want to create the figure.

- If your function calls reactive values, Shiny will update your figure whenever those values change, in a [reactive fashion](https://shiny.posit.co/py/docs/reactive-programming.html).

- Do not forget to return the plot object from your function.

3. Decorate your plotting function with a `@render_altair()` decorator.

- If your plotting function is not the same as the `id` you used in the `ui.output_widget()`, you can add an additional `@output(id=...)` decorator.

2. Define a function that returns an `altair.Chart`

3. Decorate that function with a `@render_altair`

- This decorator lets Shiny know to automatically update the chart when it's [reactive](../../../docs/reactive-programming.Rmd) dependencies (e.g., [inputs](../../#inputs)) change

cpsievert · 2025-12-04T20:38:53Z

+    - If your plotting function is not the same as the `id` you used in the `ui.output_widget()`, you can add an additional `@output(id=...)` decorator.
+:::
+
+To learn more about using Jupyter widgets with Shiny visit: [shiny.posit.co/py/docs/jupyter-widgets.html](https://shiny.posit.co/py/docs/jupyter-widgets.html).


I feel like this should come towards the end of the article (and mention that altair is just example of a Jupyter widget in Shiny)?

Oh, now I see we do this for Plotly -- I guess it's not super important, but ideally we'd have something better on both pages.

Related to this, a stretch goal (for both components) would be to have a few more "basic" variations before diving into the more complex "plots as inputs" and "plot mutation" concepts.

I also think a link to plotly/atair galleries at this point might be more useful than a link to the generic Jupyter Widgets article.

cpsievert · 2025-12-04T20:40:11Z

+we will need to use the [`shinywidgets`](https://shiny.posit.co/py/docs/jupyter-widgets.html)
+library to connect Shiny with [`ipywidgets`](https://ipywidgets.readthedocs.io/en/latest/)
+
+To make an Altair figure, we need to do the following steps:


I like how you've split the explanation up into two modes -- let's do the same for Plotly?

cpsievert · 2025-12-04T20:44:27Z

+  - title: JupyterChart update
+    description: "Shows how Shiny can access and update an Altair figure using the JupyterChart representation. This example builds on the previous basic example to show how Shiny can update the Altair figure reactively."
+    apps:
+    - title: Preview
+      file: app-variation-update-express.py
+      height: 720
+    - title: Express
+      file: app-variation-update-express.py
+      shinylive:
+      height: 720
+    - title: Core
+      file: app-variation-update-core.py
+      shinylive:
+      height: 720


I would bring the updating variations down below the "responding to user interaction" examples.

Updating (more precisely, mutating) charts in this way is more of a "only do this if you really need to for performance". Otherwise, you should just lean into the reactivity that render_altair provides

chendaniely added 2 commits November 25, 2025 19:24

altrair core and express apps

2433f0a

altair component page index start

ca79c63

chendaniely changed the title ~~altrair core and express apps~~ docs: altair component page Nov 26, 2025

github-actions Bot temporarily deployed to pr-326 November 26, 2025 03:54 Destroyed

chendaniely added 3 commits December 1, 2025 19:25

add variation and todo to fill in plot as input

eadc4f1

example express app to show hover over to shiny dataframe output

a504ff8

add altair.png to images/

1e7924d

github-actions Bot temporarily deployed to pr-326 December 2, 2025 03:59 Destroyed

chendaniely added 11 commits December 1, 2025 21:08

fix altair variation links

30fe26b

add reactive_read to relevant functions section altair

16d0e3d

fix bullet indentation

d2118da

fix typo: app-variation-select-point-express.py.py

c9d5ee3

show a transposed dataframe

d414d51

rename example to hover not select

ec75658

finish up altair section and fix file name changes

7c46fb2

altair hover core example

1a4631f

not everything is an altair index selection object

08a941e

app variation hover comment and rename typo

656ba63

altair brush point example

e96d326

github-actions Bot temporarily deployed to pr-326 December 3, 2025 07:29 Destroyed

chendaniely added 3 commits December 2, 2025 23:47

fix rendering, file refs, simplify app, remove highlight, separate ch…

3d2ae17

…art and jchart name and object

add altair variation for PointSelection data

9ebac66

typo fixes

5d20971

github-actions Bot temporarily deployed to pr-326 December 3, 2025 08:14 Destroyed

github-actions Bot temporarily deployed to pr-326 December 3, 2025 08:19 Destroyed

chendaniely requested a review from Copilot December 3, 2025 16:03

Copilot started reviewing on behalf of chendaniely December 3, 2025 16:03 View session

Copilot finished reviewing on behalf of chendaniely December 3, 2025 16:05

Copilot AI reviewed Dec 3, 2025

View reviewed changes

update variation names to match altair JupyterChart doc names

7e8c3a6

chendaniely and others added 6 commits December 4, 2025 08:44

Update components/outputs/plot-altair/index.qmd

4908d0b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update components/outputs/plot-altair/index.qmd

859ac3e

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update components/outputs/plot-altair/app-variation-selection-interva…

24b3736

…l-brush-express.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update components/outputs/plot-altair/app-variation-selection-index-h…

e0dfe91

…over-express.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update components/outputs/plot-altair/app-variation-selection-index-h…

72870c8

…over-core.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update components/outputs/plot-altair/app-variation-selection-index-h…

eded525

…over-express.py Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

github-actions Bot deployed to pr-326 December 4, 2025 17:13 View deployment

chendaniely requested a review from cpsievert December 4, 2025 17:29

chendaniely marked this pull request as ready for review December 4, 2025 17:29

cpsievert reviewed Dec 4, 2025

View reviewed changes

hpalafoxp mentioned this pull request Feb 23, 2026

3.1 Layout and Design UBC-MDS/DSCI-532_2026_12_GradSkills#29

Closed

kessler24 mentioned this pull request Feb 23, 2026

3.1 App Design and Functionality UBC-MDS/DSCI-532_2026_16_LondonCrime#23

Closed

9 tasks

meirikson mentioned this pull request Feb 23, 2026

3.1 App Design and Functionality UBC-MDS/DSCI-532_2026_15_WorldEducation#25

Closed

3 tasks

This was referenced Feb 24, 2026

Milestone 2 Overview UBC-MDS/DSCI-532_2026_31_Chartify#23

Closed

Functioning Dashboard Prototype UBC-MDS/DSCI-532_2026_31_Chartify#27

Closed

jyjzhang mentioned this pull request Feb 24, 2026

App Development UBC-MDS/DSCI-532_2026_20_non_market_housing#24

Closed

guptalavanya mentioned this pull request Feb 24, 2026

Milestone 2 Overview UBC-MDS/DSCI-532_2026_38_crime-dashboard#21

Closed

7 tasks

Roccolee18 mentioned this pull request Feb 24, 2026

App Development UBC-MDS/DSCI-532_2026_27_Supply_Chain_Dashboard#26

Closed

guptalavanya mentioned this pull request Feb 24, 2026

Functioning Dashboard Prototype UBC-MDS/DSCI-532_2026_38_crime-dashboard#35

Closed

Chikire mentioned this pull request Feb 25, 2026

Phase 3: App Design and Functionality UBC-MDS/DSCI-532_2026_17_chocosales-analyser#26

Closed

jadeeechen mentioned this pull request Feb 25, 2026

Phase 3: App Development UBC-MDS/DSCI-532_2026_29_healthy-diet#38

Closed


		To make an Altair figure, we need to do the following steps:

		::: {.panel-tabset group="syntax"}

	::: {.panel-tabset group="syntax"}
	::: {.panel-tabset .shiny-mode-tabset group="shiny-app-mode"}

	1. Import the `render_altair()` functions from `shinywidgets`.
	1. Import `render_altair` from `shinywidgets`.

		:::{#relevant-functions}
		:::

		:::{#example}
		:::

Uh oh!

Conversation

chendaniely commented Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cpsievert Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cpsievert Dec 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

chendaniely commented Nov 26, 2025 •

edited

Loading

cpsievert Dec 4, 2025 •

edited

Loading

cpsievert Dec 4, 2025 •

edited

Loading