ESPHome 2026.4.0: Climate custom mode setters deprecated

[bdraco]

Summary

ESPHome 2026.4.0 moves custom mode vectors from ClimateTraits to the Climate entity base class (PR #15206). The old ClimateTraits::set_supported_custom_fan_modes() and ClimateTraits::set_supported_custom_presets() methods are deprecated and will be removed in ESPHome 2026.11.0.

Recommended migration

Set custom modes once during setup() or codegen instead of on every traits() call:

// Before — in traits() override, called on every publish_state()
climate::ClimateTraits traits() override {
  auto traits = climate::ClimateTraits();
  traits.set_supported_custom_fan_modes({"Low", "Medium", "High"});
  traits.set_supported_custom_presets({"Eco", "Sleep"});
  return traits;
}

// After — set once, traits() gets them automatically
void setup() override {
  this->set_supported_custom_fan_modes({"Low", "Medium", "High"});
  this->set_supported_custom_presets({"Eco", "Sleep"});
}

Timeline

• 2026.4.0: Old traits setters deprecated (still work with warnings)
• 2026.11.0: Deprecated setters removed

References

• ESPHome PR: [climate] Store custom mode vectors on Climate entity to eliminate heap allocation esphome/esphome#15206
• Developer blog post: Add blog post: Climate and Fan custom mode vectors moved to entity (#15206, #15209) esphome/developers.esphome.io#123