How to Build Custom Charting Visualizations Using the OpenBB Charting Extension

To build custom charting visualizations in OpenBB, create an OpenBBFigure object with your data, wrap it with the Charting class, and call show() or to_chart() with optional ChartParams for styling.

The OpenBB charting extension provides a flexible framework for creating financial visualizations within the OpenBB-finance/OpenBB ecosystem. Whether you are building simple line charts or complex technical analysis overlays, the extension bridges raw data and publication-ready Plotly figures. This guide demonstrates how to leverage the openbb_charting package to create, customize, and export visualizations using the platform's native APIs.

Core Components of the OpenBB Charting Extension

The architecture centers on three primary classes that handle data wrapping, platform integration, and styling configuration.

OpenBBFigure Wrapper

The OpenBBFigure class, defined in openbb_platform/obbject_extensions/charting/openbb_charting/core/openbb_figure.py, inherits from Plotly's Figure object. It serves as the low-level container for trace data, layout specifications, and styling defaults. When you instantiate OpenBBFigure(data=df), you create a foundation that respects OpenBB's theme system while maintaining full compatibility with Plotly's API.

Charting Class and Entry Points

The Charting class in openbb_platform/obbject_extensions/charting/openbb_charting/charting.py acts as the high-level orchestrator. It accepts an OpenBBFigure instance, applies platform-wide defaults from user_settings.json, and resolves the correct rendering method. The class exposes two primary output methods: show() for immediate display in the terminal UI or notebooks, and to_chart(render=False) to return the Plotly object for programmatic manipulation.

ChartParams Configuration

Fine-tuning visualization appearance occurs through ChartParams, located in openbb_platform/obbject_extensions/charting/openbb_charting/query_params.py. This Pydantic model accepts parameters for titles, axis labels, legend visibility, color schemes, and export flags. When you pass ChartParams to the Charting constructor, the system automatically falls back to user-defined chart_style settings if specific values are omitted.

Step-by-Step Implementation Guide

Building a custom visualization follows a predictable four-step pattern that separates data preparation from presentation logic.

1. Create an OpenBBFigure: Initialize the figure with your DataFrame and specify the chart type (line, candlestick, bar, or heatmap).

2. Instantiate the Charting Wrapper: Pass the figure to Charting() to inherit platform defaults and enable the rendering pipeline.

3. Configure ChartParams: Define titles, colors, and layout options through the params argument.

4. Execute Show or Export: Call show() to render interactively or to_chart(render=False) to retrieve the Plotly figure for further processing.

Practical Code Examples

The following patterns demonstrate common use cases ranging from basic charts to advanced technical analysis visualizations.

Simple Line Chart with Default Settings

This example creates a basic line chart using default platform styling. The implementation references the OpenBBFigure import pattern found in openbb_platform/providers/imf/views/port_info.py.

from openbb_charting.charting import Charting
from openbb_charting.core.openbb_figure import OpenBBFigure

# Assume df is a pandas DataFrame with a DateTime index and a numeric column 'price'

fig = OpenBBFigure(data=df, title="Asset Price Over Time")
chart = Charting(fig)  # Wrap with platform charting engine

chart.show()           # Renders in UI or notebook

Candlestick Chart with Technical Analysis Overlays

For financial data visualization, you can combine candlestick charts with moving average ribbons. This pattern utilizes helper functions from the technical analysis module.

from openbb_charting.charting import Charting
from openbb_charting.core.openbb_figure import OpenBBFigure
from openbb_charting.core.plotly_ta.ta_helpers import add_moving_average

# OHLCV DataFrame ohlc

fig = OpenBBFigure(data=ohlc, chart_type="candlestick", title="Candles with MA")

# Add 20-period and 50-period SMA overlays

add_moving_average(fig, period=20, name="SMA20")
add_moving_average(fig, period=50, name="SMA50")

chart = Charting(fig)
chart.to_chart(render=False)  # Returns Plotly figure without auto-rendering

Advanced Custom Heatmap with Plotly Express

When you need visualizations beyond built-in types, wrap a native Plotly Express figure in OpenBBFigure and customize via ChartParams.

import plotly.express as px
from openbb_charting.charting import Charting
from openbb_charting.core.openbb_figure import OpenBBFigure
from openbb_charting.query_params import ChartParams

# Build custom heatmap with Plotly Express

heatmap = px.density_heatmap(
    data_frame=df,
    x="x_coord",
    y="y_coord",
    z="value",
    color_continuous_scale="Viridis",
)

# Wrap in OpenBBFigure to inherit platform defaults

obb_fig = OpenBBFigure(fig=heatmap)

# Fine-tune via ChartParams

params = ChartParams(
    title="Custom Heatmap",
    show_legend=True,
    chart_style="dark",
)

chart = Charting(obb_fig, params=params)
custom_fig = chart.to_chart(render=False)  # Returns Plotly Figure object

custom_fig.write_image("heatmap.png")

Key Source Files and Architecture

Understanding the codebase structure helps when extending or debugging charting functionality:

• openbb_platform/obbject_extensions/charting/openbb_charting/charting.py — Contains the Charting class that orchestrates figure creation and rendering.
• openbb_platform/obbject_extensions/charting/openbb_charting/core/openbb_figure.py — Implements OpenBBFigure, the Plotly wrapper with OpenBB-specific defaults.
• openbb_platform/obbject_extensions/charting/openbb_charting/query_params.py — Defines ChartParams, the Pydantic model for visualization configuration.
• openbb_platform/providers/imf/views/port_info.py — Demonstrates real-world usage of OpenBBFigure imports in provider implementations.
• openbb_platform/obbject_extensions/charting/tests/test_charting.py — Unit tests illustrating Charting.show() and to_chart() usage patterns.
• openbb_platform/obbject_extensions/charting/tests/test_charting_core_ta_helpers.py — Test suite for technical analysis helper functions used in overlays.

Summary

• The OpenBBFigure class wraps Plotly figures to add platform-specific defaults and styling inheritance.
• The Charting class in charting.py provides the main API through show() and to_chart() methods.
• ChartParams enables fine-grained control over titles, colors, legends, and export options via query_params.py.
• Custom visualizations support any Plotly-compatible figure, including those built with Plotly Express, by wrapping them in OpenBBFigure.
• Technical analysis overlays utilize helper functions from the plotly_ta module to add indicators like moving averages.

Frequently Asked Questions

What is the difference between OpenBBFigure and a standard Plotly Figure?

OpenBBFigure inherits from Plotly's Figure class and adds OpenBB-specific initialization logic, theme integration from user_settings.json, and utility methods for financial charting. While you can use a standard Plotly Figure directly, wrapping it in OpenBBFigure ensures consistency with the platform's visual identity and automatic application of user preferences.

How do I add technical indicators like moving averages to my charts?

Import helper functions from openbb_charting.core.plotly_ta.ta_helpers, such as add_moving_average(), and apply them to your OpenBBFigure instance before wrapping it with the Charting class. These helpers modify the figure's trace data in place, allowing you to layer multiple indicators over candlestick or line charts.

Can I export custom charts to static images or HTML?

Yes. When you call to_chart(render=False), the method returns a native Plotly Figure object that supports standard export methods like write_image() for PNG/SVG output or write_html() for interactive web embedding. The ChartParams configuration can also specify export paths and formats when running within the OpenBB platform environment.

Where does the OpenBB charting extension store default styling settings?

The extension references user_settings.json to determine the default chart_style (such as "dark" or "light" mode). These settings are automatically applied when you instantiate the Charting class unless explicitly overridden by passing specific parameters through ChartParams.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}