Migrating from v4 to v5

ESP-DASH v5 introduces a refined API with a dedicated class for every widget type. This guide describes the main differences from v4 and shows how to migrate existing code.

Dashboard initializationCopy Anchor Link

The ESPDash constructor now takes the AsyncWebServer instance by reference instead of by pointer.

ESPDash dashboard(&server);

ESPDash dashboard(server);

CardsCopy Anchor Link

In v4, every card was a Card object whose type was selected with a macro. In v5, each card type is its own class in the dash namespace, with its own constructor parameters and methods. Review the Cards section for each card type you use and migrate your code accordingly.

The following example migrates a temperature card:

Card temperature(&dashboard, TEMPERATURE_CARD, "Temperature", "°C");

dash::TemperatureCard temperature(dashboard, "Temperature");

Key changes:

• Use a dedicated class such as dash::TemperatureCard or dash::HumidityCard instead of Card with a type macro.
• Pass the dashboard by reference, not by pointer.
• Each card and chart class has its own set of methods.
• The generic update() method is replaced by type-specific methods such as setValue().

ChartsCopy Anchor Link

Charts are also class templates in the dash namespace. The template parameters define the types of the X-axis and Y-axis values.

Chart power(&dashboard, BAR_CHART, "Power Usage (kWh)");
power.updateX(XAxis, 7);
power.updateY(YAxis, 7);

dash::BarChart<const char*, int> power(dashboard, "Power Usage (kWh)");
power.setX(XAxis, 7);
power.setY(YAxis, 7);

Key changes:

• Use a dedicated class such as dash::BarChart or dash::LineChart instead of Chart with a type macro.
• Specify the axis types as template arguments, for example dash::BarChart<const char*, int>.
• updateX() is replaced by setX() and updateY() by setY(). Both take an array and its size.

See the Charts section for the methods of each chart type.

Interactive cardsCopy Anchor Link

Interactive cards, such as buttons and sliders, use dedicated classes and typed callbacks. The following example migrates a toggle button:

Card button(&dashboard, BUTTON_CARD, "Test Button");
button.attachCallback([&](int value) { /* ... */ });
button.update(value);

dash::ToggleButtonCard button(dashboard, "Test Button");
button.onChange([](bool state) { /* ... */ });
button.setValue(state);

Key changes:

• Use a dedicated class such as dash::ToggleButtonCard.
• attachCallback() is replaced by onChange().
• Callbacks receive a value of the appropriate type, for example bool instead of int for a toggle button.

Each interactive card has its own callback signature and methods; see the page for the card in the Cards section.

Summary of API changesCopy Anchor Link

NotesCopy Anchor Link

• v5 uses the term "widget" for all user interface elements, including cards, charts, statistics and tabs.
• Wi-Fi and web server setup is unchanged.
• dashboard.sendUpdates() still pushes all pending changes to connected clients.
• dashboard.refresh(widget) sends an update for a single widget instead of the entire dashboard. Use it, typically inside callbacks, to reduce the amount of data sent when only one widget has changed.
• In ESP-DASH Pro, each tab can have an icon. See Tabs.