Skip to content

Interactive

ninejs.main.interactive(gg, *, hover_nearest=False, reverse_hover=False, zoomable=False, width='100%', height=None, **kwargs)

Wrapper for a plotnine ggplot object to make it interactive. It automatically extracts tooltips and grouping information from the plot mapping if present.

Parameters:

Name Type Description Default
gg PlotnineChart

The original plotnine ggplot object.

 required
hover_nearest bool

If True, show tooltips for the nearest configured element while the mouse is inside the plot panel. This builds a browser-side spatial index and samples path-like SVG elements, which can add noticeable load time for very large or complex charts.

 False
reverse_hover bool

If True, dim the hovered element group instead of dimming the non-hovered elements.

 False
zoomable bool

If True, allow the reader to zoom and pan the chart with the mouse wheel and drag. This is a visual magnification of the whole plot (data, axes, ticks, and labels scale together); it does not rescale the data against fixed axes. Double-click resets the view.

 False
width Optional[int | str]

Width of the iframe representation used in environments like Quarto, Jupyter, and Positron. This does not affect saved HTML files.

 '100%'
height Optional[int | str]

Height of the iframe representation used in environments like Quarto, Jupyter, and Positron. This does not affect saved HTML files.

 None
kwargs Any

Additional arguments passed to matplotlib.pyplot.savefig().

 {} 
from plotnine import ggplot, aes, geom_point
from ninejs import interactive, css, save

p = ggplot(df, aes("x", "y", tooltip="label")) + geom_point()

(
    interactive(p)
    + css(from_file="style.css")
    + save("chart.html")
)

interactive(p, width=600, height=400)

Save to an HTML file

ninejs.main.save(file_path, *, minify=True, extra_line=True)

Utility class to save an interactive plot to an output HTML file. Set minify=True to remove whitespace between HTML tags.

Parameters:

Name Type Description Default
file_path Pathish

Path to the output HTML file.

 required
minify bool

Whether to minify HTML output. If True, whitespace is collapsed outside <script> blocks; script content is kept verbatim. The main use case for this is to avoid tracking large generated files.

 True
extra_line bool

Whether to append a trailing newline when minify is True. This is mostly useful when you track your exported HTML file and use hooks that require a trailing newline.

 True 
from ninejs import interactive, save

interactive(p) + save("output.html")
interactive(p) + save("output.html", minify=False, extra_line=False)

Export to HTML string

ninejs.main.to_html(*, minify=False, extra_line=True)

Utility class to export an interactive plot as an HTML string.

Parameters:

Name Type Description Default
minify bool

Whether to minify HTML output. If True, whitespace is collapsed outside <script> blocks; script content is kept verbatim. The main use case for this is to avoid tracking large generated files.

 False
extra_line bool

Whether to add an extra blank line when minify is True. This is mostly useful for you track your exported HTML file and use hooks that check for an extra blank line.

 True 
from ninejs import interactive, to_html

html_plot = interactive(p) + to_html()
html_plot = interactive(p) + to_html(minify=True)

Export to an iframe HTML string

ninejs.main.to_iframe(*, width='100%', height=600, title='ninejs interactive plot', sandbox='allow-scripts')

Utility class to export an interactive plot as an iframe HTML string.

Parameters:

Name Type Description Default
width int | str

Width of the iframe. If an integer, it is converted to pixels.

 '100%'
height int | str

Height of the iframe. If an integer, it is converted to pixels.

 600
title str

Title of the iframe.

 'ninejs interactive plot'
sandbox Optional[str]

Attribute to allow specific behaviors, such as running JavaScript. Learn more: https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/iframe

 'allow-scripts' 
from ninejs import interactive, to_iframe

iframe_plot= interactive(p) + to_iframe(height=650)

Show preview in editor

Tip

You might not need the show() function. In most environments, ninejs detects that it needs to display the chart. See Jupyter display.

ninejs.main.show()

Open the HTML file in the default browser or inside your code editor.

from ninejs import interactive, show

interactive(p) + show()

Jupyter display

In JupyterLab, VS Code notebooks or Positron, an interactive object renders automatically when it is the last expression in a cell. Internally, the object exposes _repr_html_() and returns the same iframe-style HTML as to_iframe().