Guide & API reference
Finish the dashboard with high-level metrics and, when appropriate, a built-in page for source data. Then configure its local server and run the completed application.
API reference
add_kpi(kpi_name, kpi_value=None)Adds a KPI card to the dashboard. KPI cards are intended for the small set of headline metrics that make the chart area easier to interpret at a glance.
dashboard.add_kpi("Monthly revenue", "$42,000")
dashboard.add_kpi("Active customers", 128)Pass a dictionary when a report has several related metrics. Each dictionary key becomes the KPI label and each value becomes its displayed value.
dashboard.add_kpi({
"Revenue": "$42,000",
"Orders": 1_248,
"Conversion": "4.6%",
})Calling the method again with the same label replaces that card’s displayed value. This is convenient when the value is calculated later in the script.
dashboard.add_kpi("Forecast", "Pending")
# ... calculate the model ...
dashboard.add_kpi("Forecast", "$58,200")Input rule: a single KPI label may be a string, integer, or float. A dictionary is also accepted. Use already formatted strings for values such as currency, percentages, or dates when you need exact presentation.
API reference
add_dataset(dataset)Adds an optional second page containing the supplied pandas DataFrame. The page includes a sortable, filterable Dash table and reports the row and column count. The dashboard header remains visible and gains a button to switch between the chart dashboard and the data page.
dashboard.add_dataset(sales)DashForge receives a dataframe, not a file path. Read the CSV with pandas first, then pass the resulting dataframe to the dashboard.
import pandas as pd
sales = pd.read_csv("data/monthly_sales.csv")
dashboard.add_dataset(sales)Create a smaller dataframe when the dashboard should expose only relevant columns or records.
reporting_columns = ["region", "month", "revenue", "orders"]
dashboard.add_dataset(sales.loc[:, reporting_columns])dashboard.add_dataset(sales)
dashboard.set_dataset_name("Monthly sales source data")Constraint: the input must be a pandas DataFrame; a list, CSV path, or dictionary raises ValueError. Add the dataset before calling hide_Header()—in practice, retain the header because it provides the necessary page navigation.
API reference
set_dataset_name(data_name)Sets the heading shown at the top of the optional dataset page. The default heading is "Data Table".
dashboard.set_dataset_name("Employee experience sample")
dashboard.set_dataset_name("Filtered transaction detail")Scenario: name the data in the language of your report so viewers immediately know whether it is source data, a filtered extract, or a reference table.
API reference
set_port(port)Sets the port used by run(). The default is 5000. Change it when that port is already in use, when running more than one dashboard locally, or when your environment expects a particular port.
dashboard.set_port(8050)
dashboard.set_port(8061)set_debug(debug)Enables or disables Dash debug mode. Debug mode is enabled by default. It is convenient while building because Dash can reload and show development diagnostics; set it to False for a quieter regular run.
dashboard.set_debug(False)API reference
build_dashboard()Creates and returns the configured dash.Dash application. Call it after you finish adding figures and settings. Keeping the returned object gives you the normal Dash application, so you can start it yourself or make direct Dash-level changes when needed.
app = dashboard.build_dashboard()
app.run(debug=False, port=8050)This uses Dash’s own app.run(). It is useful when you want to control the final server call directly or work with the generated app object.
app = dashboard.build_dashboard()
# Inspect or integrate the generated Dash app here.run()Starts the already built application using the values configured through set_port() and set_debug(). It simplifies the common workflow: configure those two Dash settings once on the Dashboard object, then use one short call instead of writing app.run(...) yourself.
dashboard.set_port(8050)
dashboard.set_debug(False)
dashboard.build_dashboard()
dashboard.run()Requirement: call build_dashboard() first, because run() starts the generated application.
Complete example
This version uses five charts so the chart grouping and custom sizes are visible: two charts in the first row, then three supporting charts in the second.
import pandas as pd
import plotly.express as px
from dashforge import Dashboard
sales = pd.DataFrame({
"month": ["Jan", "Feb", "Mar", "Apr", "May"],
"revenue": [32000, 38500, 41200, 46800, 49300],
"orders": [120, 138, 151, 164, 173],
})
sales["cumulative_revenue"] = sales["revenue"].cumsum()
revenue_chart = px.bar(sales, x="month", y="revenue")
orders_chart = px.line(sales, x="month", y="orders", markers=True)
cumulative_chart = px.area(sales, x="month", y="cumulative_revenue")
relationship_chart = px.scatter(sales, x="orders", y="revenue", text="month")
share_chart = px.pie(sales, names="month", values="orders", hole=0.45)
dashboard = Dashboard()
dashboard.set_theme("light")
dashboard.set_colors(line="#2563EB", HeaderBG="#EFF6FF")
dashboard.set_title("Monthly sales report")
dashboard.add_kpi({"Revenue": "$49,300", "Orders": 173})
dashboard.add_chart([
revenue_chart, orders_chart, cumulative_chart,
relationship_chart, share_chart,
])
dashboard.set_chart_per_row([2, 3])
dashboard.set_custom_size([
[[60, 110], [40, 110]], # Row 1: two primary charts
[[34, 82], [33, 82], [33, 82]], # Row 2: three supporting charts
])
dashboard.set_chart_titles([
"Revenue by month", "Orders by month", "Cumulative revenue",
"Revenue and orders", "Order share by month",
])
dashboard.add_dataset(sales)
dashboard.set_dataset_name("Monthly sales data")
dashboard.set_footer_text("Sales operations · July 2026")
dashboard.add_timestamp()
dashboard.set_port(8050)
dashboard.set_debug(False)
dashboard.build_dashboard()
dashboard.run()