⚖️ Finding balance: bridging React and vanilla for a cleaner UI

🚨 The problem

React is excellent for view-as-a-function-of-state UI, but not all UI components fit neatly into this model. Some UI elements work best with a more imperative, event-driven approach, since many browser APIs are inherently imperative.

Certain components—like autocomplete, calendars, and toggletips—were particularly difficult to implement cleanly in React. Toggletips, for example, required delayed re-insertion of existing DOM nodes to trigger screen readers, something impossible to do with React alone.

React's declarative model clashed with imperative APIs, making certain UI patterns difficult to implement efficiently.

⚠️ The challenges

• React's declarative model clashed with imperative APIs, making certain UI patterns difficult to implement efficiently.
• The more components we built, the more adapter boilerplate accumulated, increasing maintenance burden.
• Unnecessary re-renders impacted performance and UX.
• The key was to find a natural transition point between React’s declarative model and imperative UI interactions. Without a structured approach, integrating these two paradigms became a significant challenge.
• React's poor support for custom elements required creative workarounds, such as a roundabout way to trigger native events and a custom hook for listening to custom events.

💡 The solution

• Encapsulated imperative behavior inside custom elements, keeping React clean.
• React used custom elements just like native HTML elements, eliminating unnecessary adapter code.
• State was stored directly in the DOM, completely eliminating unnecessary re-renders.
• The same custom elements were usable in traditional server-rendered pages, making the UI framework-agnostic.

📈 The impact

By bridging React with custom elements, we created a more flexible, maintainable, and performant UI architecture.

• Reduced boilerplate code, making development faster and cleaner.
• Improved performance by eliminating unnecessary React re-renders.
• Unified component usage across both React and traditional server-rendered pages.
• Saved thousands of lines of code by leveraging simpme in-house code over heavy 3rd party libraries.
• Simplified dependency management, making future React upgrades painless by removing outdated, framework-dependent libraries.

This approach provided the best of both worlds—leveraging React where it shines while using native DOM capabilities where they’re most effective.

🎓 The lessons learned

• Balancing declarative and imperative code leads to cleaner, more efficient UIs.
• Not everything needs to be in React—often, native browser features are the best tool for the job.
• Framework-agnostic design future-proofs your UI, making it easier to integrate across different architectures.