Migrating from ESP-DASH v4 to v5

ESP-DASH v5 (Pro) introduces a refined API, better structure, and new features that improve development experience. This guide walks you through the major differences and how to migrate your code, using real examples for reference.

Dashboard Initialization

✅ What’s Changed

• No need to pass the server as a pointer.
• Initialization now uses a reference.

🔄 Before (v4)

ESPDash dashboard(&server);

✅ After (v5)

ESPDash dashboard(server);

Widget Initialization

Cards

Cards are now templated classes under dash::, with updated method names. Every card type now has its own class and set of methods, making it easier to use and understand. Please make sure to check them out in the Cards section one-by-one and migrate your code accordingly.

Here’s an quick overview of how to migrate a temperature card:

🔄 Before (v4)

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

✅ After (v5)

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

Key changes:

• Use dash::TemperatureCard instead of Card + macro.
• Pass dashboard as a reference, not a pointer.
• Now each card type has its own class, e.g., dash::TemperatureCard, dash::HumidityCard, etc.
• Each card and chart type has its own set of methods, making it more intuitive to use.
• The update() method is replaced with more specific methods like setValue().

Please refer to the specific card documentation for details on available methods.

Charts

Charts are now templated classes under dash::, with updated method names.

🔄 Before (v4)

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

✅ After (v5)

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

Key changes:

• updateX() → setX()
• updateY() → setY()
• Use dash::BarChart instead of Chart + macro.
• Charts now use template types for X and Y axes, e.g., dash::BarChart<const char*, int>.
• Each chart type has its own class, e.g., dash::BarChart, dash::LineChart, etc.
• The setX() and setY() methods now take arrays and their sizes as parameters, making it clearer how to set data.

Please refer to the specific chart documentation for details on available methods.

Interactive Elements (e.g., Buttons, Sliders)

Interactive cards now use intuitive class names and improved event handling. Here’s an example of migrating a toggle button card:

🔄 Before (v4)

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

✅ After (v5)

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

Key changes:

• Use dedicated classes like dash::ToggleButtonCard.
• attachCallback() → onChange()
• Callbacks now receive more appropriate types (e.g., bool instead of int).

Please refer to the specific interactive card documentation for details on available methods. Every interactive card type has its own callback and methods, making it easier to work with and understand.

Summary of API Changes

Notes & Compatibility

• Cards and charts are now more modular and easier to use with specific classes and each having its own set of methods & callbacks.
• We call all user interface elements “widgets” in v5. This includes cards, charts, statistics and tabs.
• Your WiFi and web server setup remains unchanged.
• dashboard.sendUpdates() is still used to push updates.
• Now you can refresh individual widgets using dashboard.refresh(widget) (usually used inside callbacks). This is useful for optimizing performance by only sending an update for a specific widget which has changed instead of the entire dashboard.
• You can now set an icon for each Tab. Please refer to Tab documentation.

Happy migrating 🚀