Charts &
layout.

API reference

add_chart

Adds visual content to the dashboard. It accepts either one Plotly Figure or a list made entirely of Plotly figures. Each call appends to the existing chart collection—it does not replace charts that were added earlier.

Pattern 1 — add one figure at a time

This is useful while your analysis creates figures in separate steps, or when conditional logic decides whether a particular chart should appear.

dashboard.add_chart(revenue_chart)
dashboard.add_chart(order_chart)

if show_forecast:
    dashboard.add_chart(forecast_chart)

Pattern 2 — add a related group in one call

Pass a list when all charts are known together. This is concise and makes the intended order obvious, which matters for later title and layout lists.

dashboard.add_chart([
    revenue_chart,
    orders_chart,
    regional_share_chart,
])

Pattern 3 — add groups over time

You can mix the two forms. The final order is the order in which figures were received across every call.

dashboard.add_chart(summary_chart)
dashboard.add_chart([trend_chart, distribution_chart])
# Card order is: summary, trend, distribution.

Input rule: a list must contain only plotly.graph_objects.Figure instances. A dictionary, a dataframe, a Plotly data trace, or a mixed list raises ValueError. Create the figure first, then pass the figure itself.

API reference

set_title

Sets the dashboard title in two places: the browser tab and the visible header. Use a concise report-level name rather than the title of one specific chart.

dashboard.set_title("FY26 commercial performance")
dashboard.set_title("Customer retention — weekly review")

Scenario: Put the time range or audience in the title when it prevents ambiguity, for example "Operations snapshot · June 2026".

API reference

preset

Chooses the dashboard layout implementation. The default and only currently supported value is "preset1", so you ordinarily do not need to call this method. It is included so future layouts can be selected explicitly.

# Optional today: this is the default.
dashboard.preset("preset1")

Constraint: unsupported preset names raise ValueError. Do not use internal layout method names; they are not part of the public API.

API reference

set_chart_per_row

Defines exactly how many chart cards appear in each dashboard row. Each number in the list represents one row, must be 1, 2, or 3, and all numbers together must equal the number of figures already added.

Pattern 1 — let DashForge choose

Do not call this method when a standard grid is enough. DashForge automatically fills rows with up to three charts. With four figures, the final dashboard has three charts in the first row and one chart in the second row.

dashboard.add_chart([fig1, fig2, fig3, fig4])
# Final layout:
# Row 1: fig1 | fig2 | fig3
# Row 2: fig4

Pattern 2 — emphasize a lead chart

dashboard.add_chart([overview, trend, map])
dashboard.set_chart_per_row([1, 2])
# Row 1: overview
# Row 2: trend | map

Pattern 3 — tell a sequence in rows

dashboard.add_chart([fig1, fig2, fig3, fig4, fig5, fig6])
dashboard.set_chart_per_row([2, 3, 1])
# Row 1: fig1 | fig2
# Row 2: fig3 | fig4 | fig5
# Row 3: fig6

Constraints: call it after add_chart(). With six charts, [2, 3, 1] is valid; [2, 2] is not because it accounts for only four. Values of 0, 4, or non-numeric items are also invalid.

API reference

set_custom_size

Changes individual chart-card widths and heights. It is deliberately precise: the list must mirror the dashboard’s row structure. Read it from outside to inside: sizes_list → one entry per row → one [width, height] pair per chart in that row.

Pattern 1 — two charts in one row

There is one row, so the outer list has one item. That row contains two charts, so it has two size pairs.

dashboard.set_chart_per_row([2])
dashboard.set_custom_size([
    [                 # Row 1
        [65, 100],    # Chart 1: 65 wide, 100 high
        [35, 100],    # Chart 2: 35 wide, 100 high
    ]
])

Pattern 2 — two charts, then three charts

There are two rows, so the outer list has two items. The first row must have two pairs; the second must have three.

dashboard.set_chart_per_row([2, 3])
dashboard.set_custom_size([
    [                 # Row 1 — two charts
        [60, 105],    # first chart
        [40, 105],    # second chart
    ],
    [                 # Row 2 — three charts
        [34, 85],     # third chart overall
        [33, 85],     # fourth chart overall
        [33, 85],     # fifth chart overall
    ],
])

Pattern 3 — customize only the important row

Use None for a row whose automatic sizing should remain untouched.

dashboard.set_chart_per_row([1, 3])
dashboard.set_custom_size([
    [[100, 115]],  # Row 1: one larger hero chart
    None,          # Row 2: DashForge's normal three-card sizing
])

Constraints: the number of outer entries must equal the number of rows. For a row of two charts, provide exactly two pairs. Each pair must contain exactly two numbers. Define set_chart_per_row() first when using a non-default row arrangement.

API reference

Card titles & subtitles

dashboard.set_chart_titles([
    "Revenue trend",
    "Orders by region",
    None,
])

dashboard.set_chart_subtitles([
    "Actuals through 30 June",
    "Color indicates sales territory",
    None,
])

API reference

set_max_buttons

A maximize button is the control on a chart card that lets a viewer expand that one chart to fill the chart area. When expanded, the other cards are hidden; selecting the control again returns to the normal grid. It is useful for dense charts where people need more room to inspect hover details, labels, or Plotly interactions.

By default, every chart receives this control. Use set_max_buttons() only when some cards should remain fixed in the normal dashboard layout. The boolean list follows the order in which charts were added: True shows the control, False removes it.

Pattern 1 — keep the default behavior

# No call needed: all chart cards can be maximized.

Pattern 2 — enable it only for detailed exploration

Keep the control for a map and a detailed trend, but omit it from simple summary charts.

dashboard.set_max_buttons([
    False,  # revenue summary: keep compact
    True,   # detailed trend: allow expansion
    True,   # map: allow expansion
    False,  # simple category chart: keep compact
])

Pattern 3 — intentionally disable all maximize controls

dashboard.set_max_buttons([False, False, False])

Constraint: provide exactly one boolean per chart. A four-chart dashboard needs four entries; a mismatched list or non-boolean value raises ValueError.