# How to Build Custom Charting Visualizations Using the OpenBB Charting Extension

> Learn to build custom charting visualizations with the OpenBB charting extension. Easily create and style charts using OpenBBFigure and Charting classes.

- Repository: [OpenBB/OpenBB](https://github.com/OpenBB-finance/OpenBB)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/imf/views/port_info.py).

```python
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.

```python
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`.

```python
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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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`](https://github.com/OpenBB-finance/OpenBB/blob/main/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**.