Add htmx v4 support

[dienhoa]

---

name: Pull Request
about: Propose changes to the codebase
title: '[PR] Add opt-in htmx v4 support'
labels: ''
assignees: ''

---

Proposed Changes
This PR adds htmx v4 support to FastHTML while keeping htmx v2 as the default behavior.

Apps can enable htmx v4 with:

app, rt = fast_app(htmx4=True)
# or app = FastHTML(htmx4=True)

The main changes are:

• Add htmx4=True support to fast_app() and FastHTML.
• Load htmx 4.x.x when htmx4=True.
• Configure htmx v4 with metaCharacter="-" so v4-style attributes and events work with Python keyword syntax.
• Add htmx v4 request headers to HtmxHeaders, including HX-Source and HX-Request-Type.
• Support htmx v4 WebSocket request payloads, including nested values and lowercase headers.
• Map extensions to v4 extension scripts when htmx4=True, including WebSocket and SSE support.
• Add FastHTML component support for htmx v4-only attributes and events.
• Add HxPartial for htmx v4 partial updates.
• Update sse_message(..., htmx4=True) so default SSE messages omit the event: line, matching htmx v4 behavior.
• Update notebook/Jupyter helpers for htmx v4 request configuration and iframe resizing.
• Update HtmxOn, PicoBusy, and session-id handling for htmx v4 event names and event detail structure.
• Add migration notes and example notebooks covering request headers, event structure, WebSockets, SSE, partials, and attribute inheritance.
• Add compatibility-checker fixtures for identifying obvious v2/v4 attribute and event mismatches.

htmx v2 remains the default. Existing apps using fast_app() or FastHTML() without htmx4=True should continue using the existing htmx v2 behavior.

Existing FastHTML projects can use the compatibility checker during migration to htmx v4. It scans Python source files for htmx attributes and event handlers that are specific to htmx v2 or htmx v4, then reports cases where they do not match the target version.

python htmxv4_migration/htmx_compat_checker.py --path path/to/project

The migration documentation and examples are included in the htmxv4_migration/ folder.

Types of changes
What types of changes does your code introduce? Put an x in all the boxes that apply:

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Checklist
Go over all the following points, and put an x in all the boxes that apply:

• My code follows the code style of this project.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• I have added tests to cover my changes.
• All new and existing tests passed.
• I am aware that this is an nbdev project, and I have edited, cleaned, and synced the source notebooks instead of editing .py or .md files directly.

[dienhoa]

@curtis-allan @jph00