Fan preset mode changes introduced in 2025.11

[gapple]

Description:

2025.11 changed the preset_mode property to has/get/set methods.

get_preset_mode() now returns a null pointer when a value is not set, instead of the previous property being an empty string, which is worth noting in the documentation.

Related issue (if applicable): fixes

Pull request in esphome with YAML changes (if applicable):

• [fan] Remove duplicate preset mode storage to save RAM esphome#11632

Checklist:

• I am merging into next because this is new documentation that has a matching pull-request in esphome as linked above.
  or

• I am merging into current because this is a fix, change and/or adjustment in the current documentation and is not for a new component or feature.

• Link added in /components/_index.md when creating new documents for new components or cookbook.

New Component Images

If you are adding a new component to ESPHome, you can automatically generate a standardized black and white component name image for the documentation.

To generate a component image:

1. Comment on this pull request with the following command, replacing component_name with your component name in lower_case format with underscores (e.g., bme280, sht3x, dallas_temp):

   @esphomebot generate image component_name
   

2. The ESPHome bot will respond with a downloadable ZIP file containing the SVG image.

3. Extract the SVG file and place it in the /static/images/ folder of this repository.

4. Use the image in your component's index table entry in /components/_index.md.

Example: For a component called "DHT22 Temperature Sensor", use:

@esphomebot generate image dht22

[esphome]

As this is a feature matched with a PR in https://github.com/esphome/esphome, please target your PR to the next branch and rebase.

[esphome]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[netlify]

✅ Deploy Preview for esphome ready!

Name	Link
🔨 Latest commit	17f7170
🔍 Latest deploy log	https://app.netlify.com/projects/esphome/deploys/695c651ea6e4e00008abe0ee
😎 Deploy Preview	https://deploy-preview-5869--esphome.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai]

Walkthrough

Documentation update to the fan component that replaces direct preset_mode property access with a new public API consisting of get_preset_mode(), set_preset_mode(), and has_preset_mode() methods. Examples and references are updated accordingly.

Changes

Cohort / File(s)	Summary
Fan preset mode API documentation content/components/fan/_index.md	Removes direct preset_mode primitive accessor documentation and old example usage. Introduces new public API methods (get_preset_mode(), set_preset_mode(), has_preset_mode()). Adds new conditional usage examples demonstrating the updated API. Updates "See Also" references from fan_state.h to fan.h.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Suggested labels

current

Suggested reviewers

• clydebarrow

Pre-merge checks

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Fan preset mode changes introduced in 2025.11' is directly related to the main change: documenting the conversion of preset_mode from a property to get/set/has methods in the 2025.11 release.
Description check	✅ Passed	The description is directly related to the changeset, explaining the 2025.11 changes to preset_mode methods and the behavioral difference regarding null pointers versus empty strings.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

📜 Recent review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1ce3a04 and 17f7170.

📒 Files selected for processing (1)

• content/components/fan/_index.md

🧰 Additional context used

📓 Path-based instructions (1)

**

⚙️ CodeRabbit configuration file

• Do not generate or add any sequence diagrams

Files:

• content/components/fan/_index.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: esphome/esphome-docs PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-24T00:13:13.459Z
Learning: Open pull requests against the correct base branch: use `current` for documentation-only revisions and `next` for changes tied to new features in esphome/esphome

Learnt from: jesserockz
Repo: esphome/esphome-docs PR: 4865
File: .github/workflows/needs-docs.yml:0-0
Timestamp: 2025-05-01T03:29:47.922Z
Learning: In the esphome-docs repository, the "current" label is automatically added by a bot to pull requests, making it a reliable indicator for the target branch.

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: Build

🔇 Additional comments (1)

content/components/fan/_index.md (1)

375-391: Documentation updates for preset_mode API are accurate and complete.

The new lambda examples correctly demonstrate the three-method preset_mode API with proper defensive checks. The warning about get_preset_mode() returning a null pointer (lines 379–380) is accurate and well-placed, and the usage pattern—checking has_preset_mode() before dereferencing—matches safe C++ practices. The write example correctly shows set_preset_mode() integrated with the turn_on() action pattern, and fan/fan.h is the correct header reference for the public API.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gapple]

The fan.h API page also currently appears to be outdated, still showing the previous property instead of the new methods:
https://api-docs.esphome.io/fan_8h

Stale

[swoboda1337]

Thanks