feat: replace x-editable with HTMX for inline editing

[hasansezertasan]

Summary

• Replace the unmaintained x-editable library with HTMX for theme-agnostic inline editing in list views
• Net result: -702 lines (249 added, 951 removed)
• The column_editable_list API is unchanged — no user-facing breaking changes

Fixes #1615

Changes

Component	Before	After
Widget	XEditableWidget (125 lines, 12+ field type mappings)	HTMXEditableWidget (30 lines, field-agnostic)
JS	~70 lines x-editable init code	~20 lines HTMX afterSwap handlers
Vendor	x-editable CSS + JS (~670 lines)	HTMX 2.0.8 min.js (14KB gzipped)
Endpoints	POST /ajax/update/ → plain text	GET /ajax/edit/ (new) + POST /ajax/update/ → HTML fragments

How it works

1. User clicks an editable cell → HTMX sends GET /ajax/edit/?pk=X&field=Y
2. Server returns an edit form HTML fragment → HTMX swaps it into the <td>
3. User edits and presses Enter → HTMX sends POST /ajax/update/
4. Server validates, saves, returns the updated display fragment → HTMX swaps it back
5. Cancel (Escape key or button) restores the original content client-side (no round-trip)

Why HTMX

• Theme-agnostic: No CSS framework dependency — works with Bootstrap 4, Bootstrap 5, Tabler, or any future theme
• Simpler architecture: Server renders everything, client just swaps HTML fragments
• Less JS to maintain: Field-type logic moves from client-side JS to server-side WTForms rendering
• Active project: HTMX is actively maintained vs x-editable which hasn't been updated in years

Test plan

• All existing SQLAlchemy editable list tests pass (165 passed)
• All existing Peewee editable list tests pass (11 passed)
• New test_ajax_edit_endpoint covers: valid field, non-editable field (404), non-existent record (404), no column_editable_list (404)
• Validation errors re-render edit form with error markup
• Special primary keys (strings with hyphens) work correctly
• CSRF token conditional guard works with both SecureForm and BaseForm
• No x-editable references remain in production code
• Manual testing with the demo script below

Manual testing

Run the "sqla_column_editable" example to test inline editing interactively.

What to test manually

1. Click to edit: Click any cell in Name/Email/Active columns → should show inline input
2. Save: Change value, press Enter or click ✓ → value updates without page reload
3. Cancel: Press Escape or click ✗ → reverts to original value
4. Boolean field: Click Active column → should show Yes/No dropdown
5. Validation: Try submitting an empty required field → should show error inline

[hasansezertasan]

I'd be more into showing a modal for update forms.

[ElLorans]

Wow!! You say test passed but how many are testing the actual code changes?

[ElLorans]

Also, this looks like a breaking change to me. If that's the case should either release this in 3.0, or provide a variable/parameter to switch.

[hasansezertasan]

Wow!! You say test passed but how many are testing the actual code changes?

Could you please provide more detailed information 🤓?

Also, this looks like a breaking change to me. If that's the case should either release this in 3.0, or provide a variable/parameter to switch.

I taught the same. The breaking change to me seemded like "XEditableWidget", so I did a quick search for XEditableWidget on GitHub but couldn't find any implementor worth mentionable.

Is it possible to determine if it's a breaking change or not?

[hasansezertasan]

Some LLM:

---

I did a GitHub-wide search for XEditableWidget imports outside of flask-admin — found zero external usage.

The backwards compatibility alias is already in place:

# flask_admin/model/widgets.py:113
XEditableWidget = HTMXEditableWidget

So from flask_admin.model.widgets import XEditableWidget still works and returns HTMXEditableWidget.

The one theoretical breaking case: someone who subclassed XEditableWidget and overrode get_kwargs() (the old method that handled select/source field-type mappings). That method no longer exists since the new widget is field-agnostic — the server renders the proper input via WTForms. But given zero external implementations found, this seems safe.

The alias can be removed with a deprecation warning in a future major version if desired.

[samuelhwilliams]

Comment from the sideline - sorry - none of this is yet me weighing in on whether I support this change or not (or have even understood it yet!).

I did a GitHub-wide search for XEditableWidget imports outside of flask-admin — found zero external usage.

I did a non-LLM GitHub-wide search for this and I did find some external uses, eg:

• https://github.com/Drc3p0/MakerManager2/blob/ebecd2c8947d049097e8b65df8452ef0f05bae13/application/views/badges.py#L14
• https://github.com/erdal-pb/overhave/blob/19d5050b746491ef73a3c2133a56dd776e83ed00/overhave/admin/views/index/custom_page.py#L5

That said, these codebases haven't been touched in a while.

I think should recognise that this isn't a backwards-compatible change and decide what level of risk tolerance we have for doing this without a full deprecation cycle. This comment isn't meant to steer strongly in either direction. You can decide that we prioritise our own speed in merging this over breaking one or two people, or you can decide that we try to stick with a stricter deprecation policy.

Do you have thoughts on how much overhead we're looking at if we deprecate this through adding a new component and leaving the existing XEditableWidget untouched?

[samialfattani]

maybe the right question is, why we are stricting to deprecate something that is already not supported, not functioning well, not compatible for future UIs ? to me, our users would be happy if we provide them a better, stable, and permenant solution with a little cost of breaking change.
to the best of my knowledge, XEditableWidget depends on JQuery which is inteded to be removed from flask-admin .

[samuelhwilliams]

Because we are supporting it by having it in Flask-Admin. When a project takes on a dependency it's an implicit commitment to supporting that for our users, even if it is deprecated upstream. It's not fun for users when projects make breaking changes without giving adequate warning or time to migrate.

In my opinion this is simply the cost of providing stable software for an ecosystem.

I think there's potential to say the benefits of just swapping out directly outweigh the risks/disruption for users, but that isn't a decision to make without some consideration or understanding of the impact.

None of this is to say that I couldn't be convinced that just doing a straight swap here will be 'fine', so consider all of this commentary/conversation rather than edict.

[hasansezertasan]

Comment from the sideline - sorry - none of this is yet me weighing in on whether I support this change or not (or have even understood it yet!).

Actually, the issues I had with x-editable at #2444 motivated me to work on this.

I've used skycyclone/x-editable over there, but that hasn't received any updates in the last 5 years either.

That got me thinking about alternatives, and I gave HTMX a try — it worked! 🥂 I did have to add some CSS to make it look a bit more polished, though.

I believe this work is a stepping stone toward better custom theme support.

I think should recognise that this isn't a backwards-compatible change and decide what level of risk tolerance we have for doing this without a full deprecation cycle. This comment isn't meant to steer strongly in either direction. You can decide that we prioritise our own speed in merging this over breaking one or two people, or you can decide that we try to stick with a stricter deprecation policy.

After giving it more thought, I agree with you — this is not a backwards-compatible change. I think we should discuss the deprecation policy and our vision for the user interface further before moving forward.

Do you have thoughts on how much overhead we're looking at if we deprecate this through adding a new component and leaving the existing XEditableWidget untouched?

The idea that led me to this PR: dropping Bootstrap 4 is overhead in itself.

I think we should talk about this topic thoroughly — what we want to do, where we want to go, and what we want to achieve.

[ElLorans]

I think making this not a breaking change is not possible (correct me if I am wrong), but I agree the "breaking" is minor.
Here are the alternatives I see, sorted by my preferences:

1. We add it with tabler and/or bootstrap 5 (@princerb was working on something similar in [Theme] New theme: FomanticUI [beta] #2643 ) as an alternative to bootstrap 4
2. We bring it in 3.0
3. Bring it in the next minor release, accept the risk of the breaking

[hasansezertasan]

After thinking about this more and reading everyone's feedback, I'd like to propose Option 1 with a twist.

Instead of tying the HTMX inline editing to a BS5/tabler theme (which depends on PR #2643), I'm proposing a "vanilla" theme — a dependency-free foundation that uses only semantic HTML, minimal custom CSS, and HTMX as the sole JS dependency. No jQuery, no Bootstrap, no Font Awesome.

I explored this idea through a brainstorming session with Claude Code (Opus), where I guided the design decisions and it helped me think through the architecture and write up the spec.

Why vanilla?

• BYO Theme foundation — The vanilla theme outputs clean semantic HTML that works as a starting point for any CSS framework: BS2-5, Tabler, Tailwind, PicoCSS, or custom. Flask-admin renders HTML, you bring the styles.
• Testing baseline — A minimal, predictable theme that Playwright tests can target without fighting Bootstrap's dynamic classes, animations, or JS timing.
• Migration path clarity — By building a fully functional theme without BS4, we get concrete answers about what breaks and what the migration looks like.
• Proves HTMX viability — Inline editing, modals (via native <dialog>), and all interactive features work with HTMX + ~175 lines of vanilla JS, replacing jQuery + Bootstrap JS + Select2 + 8 admin JS files.

To demonstrate adoptability, I'd also ship a "picocss" theme alongside it — extending the vanilla templates and just swapping in PicoCSS (~10KB classless CSS). If the vanilla HTML is truly semantic, PicoCSS should "just work" with minimal overrides.

BS4 stays untouched and remains the default. The original XEditableWidget and ajax/* endpoints are restored for BS4. The vanilla theme gets its own HTMXEditableWidget and new RESTful /inline/<pk>/<field>/ endpoints. No backward-incompatible changes.

There's a full design spec behind this. Happy to share if there's interest in discussing the details.

Thoughts?

---

Of course this is just an idea, the possible output might not be exactly like that.

[samuelhwilliams]

I'm proposing a "vanilla" theme — a dependency-free foundation that uses only semantic HTML, minimal custom CSS, and HTMX as the sole JS dependency. No jQuery, no Bootstrap, no Font Awesome.

I'm really in favour of this idea. It's been in the very back of my mind (in a very light way) that it would be nice if Flask-Admin had a very clear 'theming' API/interface that was well defined to support all of the actions needed for this vanilla API, and then use that. I think it would be great if themes for Flask-Admin could be published as separate packages and then just 'plugged in'. I suspect this requires quite a lot of up front thinking through and would be a big undertaking.

While working on a theme myself for some work projects I did have to mangle quite a lot of things and hit some flask-admin internals, so it's not a very clean process. Right now a lot of the functionality required for bootstrap is fairly closely integrated/coupled with flask-admin internals itself, so it'd be really great to detangle some of that.

I'd also strongly prefer that any new 'vanilla' theme we work towards is progessively enhanced, ie resilient to failures in JS (following best practice principles from eg GOV.UK: https://www.gov.uk/service-manual/technology/using-progressive-enhancement - I'm aware this is my specific context a lot of the time, but I think still a strong foundation). UX improvements should ideally be layered on top of that to provide a more full and modern experience.

[ElLorans]

I agree with everything you are saying, but we already have closed PR and open PRs just to bring a new theme, and this suggestion increases the workload without bringing us further. My personal opinion is that we should push to get a bootstrap5/tabler whatever template, and then we can refactor from there.

[samuelhwilliams]

That approach is fine with me!

[ElLorans]

Errors are not rendered. E.g.: if the user submits a non unique field on a unique constrained column, only a console error is registered.

[ElLorans]

Error msg fixed, I opened #2909 against master to check the rebase was correct and then vs this branch.

1. Do we need to change AjaxSelect2Widget?
2. Do we want to try and reduce the breaking changes? I have no clue how to do that but if I restore the old test suite I can try, the issue is that it would take time for little, not guaranteed benefits

EDIT:

1. We do not need to change other widgets
2. Avoiding the breaking changes is not really feasible: the current API uses get_kwargs which muddles CSS classes with backend args. I do not see a way of sustaining the old API and a new one with another template not using bootstrap classes

[ElLorans]

I think making this not a breaking change is not possible (correct me if I am wrong), but I agree the "breaking" is minor. Here are the alternatives I see, sorted by my preferences:

1. We add it with tabler and/or bootstrap 5 (@princerb was working on something similar in [Theme] New theme: FomanticUI [beta] #2643 ) as an alternative to bootstrap 4
2. We bring it in 3.0
3. Bring it in the next minor release, accept the risk of the breaking

After thinking about this more and reading everyone's feedback, I'd like to propose Option 1 with a twist.

Instead of tying the HTMX inline editing to a BS5/tabler theme (which depends on PR #2643), I'm proposing a "vanilla" theme — a dependency-free foundation that uses only semantic HTML, minimal custom CSS, and HTMX as the sole JS dependency. No jQuery, no Bootstrap, no Font Awesome.

After working on #2910, I have a different perspective vs my previous statements and hasanzerstan opinion.
Option1 with a twist is not possible without the breaking change. A vanilla theme would still need HTMX and maintaining the 2 different APIs is not only more work, but also means changing theme requires the users relying on Ajax and column_editable to change their code together with the template,

The “breaking change” concern is real but modest. @samuelhwilliams found two external XEditableWidget usages, both in repos untouched for years. The ajax/update/ response format change is also exactly the kind of thing a major version bump communicates clearly.

I would propose to release 3.0 (a new major release) including:
• Tabler with HTMX inline editing support from day one (as I am already doing in #2910)
• XEditableWidget entirely removed with no alias to "fail fast" during the upgrade process
• A migration guide covering: the JS response format change, get_kwargs removal, and x-editable vendor removal
• If possible, Fomantic adopting htmx

[samuelhwilliams]

If were doing large-scale work on theme support I'd be very keen to start with a bit of high level analysis. I haven't discussed this with anyone, or deeply formulated my thoughts, but I'd be keen to get to a place where flask admin themes are highly pluggable and use a clearly defined and publicly exposed+documented set of APIs.

I don't want to block progress of this if there's little appetite for the wider thinking at the moment, but I think a bit of a reset and design documented for the goals and shape of what needs to be exposed and how would be super useful. At the moment I maintain a separate flask admin theme as a python package and it does have to hack around quite a bit.

I feel like a V3 release having a really clean way of building your own themes would be a great feature for the next major release.

[ElLorans]

You mentioned that back in #2682. I can take a look, but frontend is not my specialty: you, Princerb and hasanzerstan are the ones that probably know flask admin themes the best, so I would rely on your guidance.