RFC: Making templUI Framework-Agnostic - Decoupling from HTMX/Datastar

[axzilla]

Hey templUI community! 👋

I'm considering a major architectural change that would make templUI completely framework-agnostic and I'd love your thoughts.

🤔 Current Problem

Right now, templUI components have hardcoded event listeners for HTMX:

// Current approach - tightly coupled to HTMX
document.body.addEventListener("htmx:afterSwap", handleHtmxSwap);
document.body.addEventListener("htmx:oobAfterSwap", handleHtmxSwap);

This creates several issues:

• ❌ Users constantly ask about Datastar support
• ❌ Not future-proof for new frameworks
• ❌ Forces templUI to know about specific frameworks
• ❌ Makes testing harder
• ❌ Limits adoption

🚀 Proposed Solution: Clean Global API

Instead, expose clean initialization functions:

// New approach - framework agnostic
window.templUI = {
  modal: {
    init: initModal,           // Single component
    initAllComponents: initAllComponents,  // Batch init
    open: openModal,           // Public API
    close: closeModal
  },
  carousel: {
    init: initCarousel,
    initAllComponents: initAllComponents,
    goToNext: goToNext,
    goToPrev: goToPrev
  }
  // ... all components follow same pattern
}

🔧 Framework Integration (User's Choice)

HTMX Users:

document.body.addEventListener("htmx:afterSwap", (e) => {
  Object.values(window.templUI).forEach(comp => 
    comp.initAllComponents?.(e.detail.elt)
  );
});

Datastar Users:

// Datastar handles this automatically via MutationObserver
// Or manual trigger when needed
window.templUI.modal.initAllComponents(changedElement);

Alpine.js Users:

document.addEventListener('alpine:init', () => {
  Alpine.directive('templui-init', (el) => {
    Object.values(window.templUI).forEach(comp => 
      comp.initAllComponents?.(el)
    );
  });
});

Vanilla JS Users:

// Just works!
window.templUI.modal.initAllComponents(document);

✅ Benefits

• 🎯 Framework Agnostic: Works with anything
• 🔮 Future Proof: Ready for whatever comes next
• 🧹 Cleaner Code: Separation of concerns
• 📚 Better DX: Consistent APIs across all components
• 🧪 Easier Testing: No framework dependencies
• 🚀 Broader Adoption: Not tied to specific ecosystems

🤝 Migration Strategy

1. Phase 1: Refactor one component (modal) as proof of concept
2. Phase 2: Create helper utilities for common integrations
3. Phase 3: Migrate all components
4. Phase 4: Update docs with integration examples

🏗️ Implementation Details

Current Modal Component Structure:

(function () {
  function initAllComponents(root = document) {
    // Initialize triggers, close buttons, etc.
  }
  
  // OLD: HTMX-specific listeners
  document.body.addEventListener("htmx:afterSwap", handleHtmxSwap);
  document.body.addEventListener("htmx:oobAfterSwap", handleHtmxSwap);
})();

New Modal Component Structure:

(function () {
  function initAllComponents(root = document) {
    // Same initialization logic
  }
  
  // NEW: Expose clean API
  if (!window.templUI) {
    window.templUI = {};
  }
  
  window.templUI.modal = {
    init: initAllComponents,
    initAllComponents: initAllComponents,
    open: openModal,
    close: closeModal
  };
  
  // Still auto-init on DOM ready
  document.addEventListener("DOMContentLoaded", () => initAllComponents());
})();

📖 Documentation Examples

Quick Start (Any Framework)

<!-- Include templUI components -->
<script src="/js/templui/modal.js"></script>
<script src="/js/templui/carousel.js"></script>

<!-- Choose your integration -->
<script>
  // For HTMX users
  document.body.addEventListener("htmx:afterSwap", (e) => {
    Object.values(window.templUI).forEach(comp => 
      comp.initAllComponents?.(e.detail.elt)
    );
  });
  
  // For manual control
  // window.templUI.modal.initAllComponents(document);
</script>

Integration Helper (Optional)

// We could provide a helper for common patterns
window.templUI.integration = {
  htmx: () => {
    document.body.addEventListener("htmx:afterSwap", (e) => {
      Object.values(window.templUI).forEach(comp => 
        comp.initAllComponents?.(e.detail.elt)
      );
    });
  },
  
  datastar: () => {
    // MutationObserver setup for Datastar compatibility
  },
  
  generic: () => {
    // Generic MutationObserver for any framework
  }
};

// Usage: window.templUI.integration.htmx();

💭 Questions for the Community

1. Does this approach make sense for your use case?
2. Would you prefer a helper like templUI.integration.htmx() that sets up common patterns?
3. Any concerns about the migration path?
4. What other frameworks should we consider in our docs?
5. Should we maintain backward compatibility or make this a breaking change?

🔄 Migration Path for Users

Before (Current):

<script src="/js/templui/modal.js"></script>
<!-- Components automatically work with HTMX -->

After (New):

<script src="/js/templui/modal.js"></script>
<script>
  // Choose your integration
  window.templUI.integration.htmx(); // One-liner for HTMX users
  // OR manual setup for custom frameworks
</script>

🎯 Success Metrics

This change would be successful if:

• ✅ Datastar users can easily integrate
• ✅ New frameworks work without templUI changes
• ✅ Existing HTMX users have smooth migration
• ✅ Testing becomes easier
• ✅ Code is cleaner and more maintainable

---

This change would make templUI truly universal while keeping the same great DX. What do you think?

[vague2k]

TLDR; i don't care about the opinion piece

• Exposing a component's JS for those who need extra control / custom functionality? GOOD!
• Rewriting JS that's already been written for me in past versions of TemplUI? BAD I DON'T WANT THIS!
• A simple integration helper function like window.templUI.integration.htmx(); for common patterns? GREAT! I PREFER THIS

The opinion piece

The reason I use TemplUI is because I don't want to write JS or spend time thinking about "frontend interactivity" or "component reactivity" unless I absolutely have to because quite frankly that's not the business i'm in and it's not the business I want to be in. I just want to write my endpoints in go, have the client call them and show HTML on the screen, as expected, in the way i expect it and have a dropdown just work.

I don't know what vision you have for this project, although i can imagine it being more than what it currently is considering the development of TemplUI Pro, but with that being said...

One can argue that TemplUI being focused on HTMX is not necessarily a bad thing considering HTMX is the most popular tool. You probably have a better idea of this then me so I could be totally just be wrong, but why rethink a model because of a couple of people who aren't using the currently accepted standard? If i was the maintainer, unless I had multiple issues on a regular basis asking for specific support on "XYZ" framework, I would consider it a non priority. And this is not what I have seen skimming through issues and pull requests, where the majority of people seem to be concerned primarily with HTMX.

Like how the saying goes "premature optimization is bad" The same sentiment can be said about future proofing to a certain extent.
Why cause extra work for yourself when there's no pressure to? unless of course... you want to because you can which I can respect lol

[delaneyj]

Datastar author here. You do you. Don't let anyone push your project in a way that goes against what you want to produce. I'll be starting soon on lib that let you do backed agnostic UI libs so tell Datastar supporter to buzz off if you choose.

However I definitely don't think HTMX is gonna be the last form of hypermedia first approach takes. Maybe leave at is and a fresh start a new project? I'd love to have a vidchat about your effort and if there is collaboration in the future.

[axzilla]

Thanks for the honest feedback!

templUI is still < v1.0, so breaking changes will happen occasionally – but I’ll do my best to make transitions smooth and well-documented.

And no worries: things will continue to "just work" out of the box for folks who don’t want to write JS.

[axzilla]

Datastar author here. You do you. Don't let anyone push your project in a way that goes against what you want to produce. I'll be starting soon on lib that let you do backed agnostic UI libs so tell Datastar supporter to buzz off if you choose.

However I definitely don't think HTMX is gonna be the last form of hypermedia first approach takes. Maybe leave at is and a fresh start a new project? I'd love to have a vidchat about your effort and if there is collaboration in the future.

@delaneyj Really appreciate your message and support – means a lot, especially coming from someone building in a similar space.
For now I’m focused on evolving templUI in its current form. I'm not looking to spin off a new project or collaborate at the moment, but I’m definitely curious to see what you come up with!

Let’s stay in touch and see where things go.

[chris-perardi]

My startup is developing an admin panel pattern application using TemplUI.

For my very particular use case, I would support this change, as long as HTMX is a “first among equals”. We are heavily invested in HTMX, and have no real interest in other hypermedia frameworks. Documentation and guidance for adapting and migrating to this new pattern would be appreciated.

I do see the merit of having a generic MutationObserver, though. That would be nice.

[axzilla]

Really appreciate you sharing this – and great to hear TemplUI is being used in a startup context like that.

HTMX will absolutely remain a first-class citizen. The plan is to remove hard coupling, not support.

Migration and integration examples will be documented clearly, and the MutationObserver pattern is definitely part of the plan.

Thanks again for the thoughtful input!

[glsubri]

I am currently rewriting a new version of my SaaS and am using HTMX. I don't think I will change to another hypermedia-first library, but I understand why it would make sense for templUI to be agnostic about it.

That said, as long as it's relatively easy to integrate with HTMX, I don't really care.

OTOH, if these changes were to be made, I believe it would also have an impact on other parts of the components library. The JS integration is one thing, but what about the props of the components?

Let's take a look at the props of the button:

type Props struct {
	ID           string
	Class        string
	Attributes   templ.Attributes
	Variant      Variant
	Size         Size
	FullWidth    bool
	Href         string
	Target       string
	Disabled     bool
	Type         Type
	HxGet        string
	HxPost       string
	HxPut        string
	HxDelete     string
	HxTrigger    string
	HxTarget     string
	HxSwap       string
	HxReplaceUrl string
}

If HTMX is not the default/standard for this component library, does it really make sense to have all of the HTMX-related props? Would we keep them and just add all the ones necessary for other libraries? Would we remove them? Would we have some kind of modular components where the only one presents are the one you select (templui init --with-htmx or something of that sort)?

And I have to say, while it's not a huge deal to not have these HTMX-related props, it does make it very nice to use. It would be a shame if they were to go...

In any case, I'm glad to have access to this library and have good looking components in templ.
Thanks for the work ❤️

If there was a need for some work that you wish to be done, don't hesitate to contact me

[axzilla]

Thanks so much for the thoughtful feedback!
I totally get how convenient the built-in HTMX props are – and I’ve enjoyed using them myself.
That said, to keep templUI sustainable and truly agnostic, I’m moving framework-specific attributes into templ.Attributes.
It’s a tradeoff, but I think it’s the cleanest way forward. And of course, HTMX will still be well supported through docs and examples.
Appreciate your support – and really glad templUI is useful in your stack!

[axzilla]

Thanks again to everyone who contributed ideas, feedback, and pushback – it really helped shape this!

✅ The refactor is now live in templUI v0.80.2

Full release notes & migration details here:
👉 https://github.com/axzilla/templui/releases/tag/v0.80.2

This is a big step toward making templUI fully framework-agnostic while keeping HTMX and others easy to use via templ.Attributes.

We’re still pre-1.0 – so yeah, things might break. If something doesn’t work as expected, let me know and I’ll fix it quickly.

Let’s build clean, portable UIs for Go & templ – together 🚀