Choosing the UI Abstraction Level in Appcelerator Titanium: Ti.UI vs Native Modules

Decision and Constraints

When you start a new Titanium project or refactor an existing one, the first architectural choice is how to build the user interface. The SDK ships with Ti.UI, a cross‑platform wrapper that maps JavaScript calls to native iOS and Android views. Since SDK 8 the Alloy MVC framework is deprecated, so the only officially supported paths are:

• Pure Ti.UI imperative JavaScript.
• Direct native UI via Hyperloop or custom native modules (iOS Swift/Obj‑C, Android Kotlin/Java).

Constraints that shape the decision include:

• Team expertise – JavaScript‑centric vs native‑mobile experience.
• Performance budget – extra indirection of Ti.UI versus zero‑overhead native calls.
• Maintenance surface – single codebase vs separate iOS/Android UI code.
• Future compatibility – Alloy is no longer maintained; any new Alloy code will become technical debt.

Option Comparison

Trade‑offs

When Ti.UI Wins

If the app uses standard controls (buttons, tables, scroll views) and the team is comfortable with JavaScript, Ti.UI delivers a maintainable, single‑source UI. The abstraction also handles platform‑specific defaults (e.g., Material ripple on Android, rounded corners on iOS) automatically.

When Native Modules Win

Complex animations, custom drawing, or platform‑only widgets (iOS SF Symbols, Android Jetpack Compose interop) exceed Ti.UI capabilities. Native modules give you the full SDK, but you must duplicate UI logic and keep two codebases in sync.

Hybrid Approach

Most production apps adopt a hybrid: core screens in Ti.UI, performance‑critical or brand‑specific components in native modules. This limits native surface area while still accessing platform‑unique features.

Concrete Implementation

Cross‑platform button with Ti.UI

// app/controllers/index.js
const win = Ti.UI.createWindow({ backgroundColor: '#fff' });
const btn = Ti.UI.createButton({
  title: 'Tap Me',
  top: 100,
  width: 200,
  height: 44,
  // Platform‑specific styling is applied automatically
});
btn.addEventListener('click', () => {
  Ti.API.info('Button clicked via Ti.UI');
});
win.add(btn);
win.open();

Native iOS button via Hyperloop (Swift)

// app/lib/ui/NativeButton.swift
import UIKit
@objc public class NativeButton: UIView {
  private let button = UIButton(type: .system)
  public override init(frame: CGRect) {
    super.init(frame: frame)
    button.setTitle("Native Tap", for: .normal)
    button.addTarget(self, action: #selector(tapped), for: .touchUpInside)
    addSubview(button)
    button.translatesAutoresizingMaskIntoConstraints = false
    NSLayoutConstraint.activate([
      button.leadingAnchor.constraint(equalTo: leadingAnchor),
      button.trailingAnchor.constraint(equalTo: trailingAnchor),
      button.topAnchor.constraint(equalTo: topAnchor),
      button.bottomAnchor.constraint(equalTo: bottomAnchor)
    ])
  }
  required init?(coder: NSCoder) { fatalError() }
  @objc private func tapped() {
    // Bridge back to JS via Ti.App.fireEvent
    TiApp.fireEvent('nativeButtonTapped', nil)
  }
}

Register the class in hyperloop.json and use it from JavaScript:

// app/controllers/index.js (hybrid)
const Hyperloop = require('hyperloop');
const NativeButton = Hyperloop.requireClass('NativeButton');
const nativeBtn = new NativeButton({ frame: { x: 50, y: 200, width: 200, height: 44 } });
win.add(nativeBtn);
Ti.App.addEventListener('nativeButtonTapped', () => {
  Ti.API.info('Native button tapped');
});

Validation Steps

1. Confirm SDK version – run ti info in the project root (requires CLI install). Verify the output shows Titanium SDK: 12.x.x (or your target version).
2. Inspect generated manifests – after a build (ti build -p ios or ti build -p android), open build/iphone/Info.plist and build/android/AndroidManifest.xml. Ensure the native module entry (e.g., NativeButton) appears under UIApplicationDelegate or application tags respectively.
3. Smoke test on both emulators – launch the app on an iOS simulator and an Android emulator. Verify the Ti.UI button renders with platform default styling and the Hyperloop button appears with the exact frame you set.
4. Performance spot‑check – use Xcode Instruments (Time Profiler) and Android Studio Profiler to compare UI thread time for a screen with 20 Ti.UI buttons vs 20 native buttons. Expect a measurable reduction in bridge calls for the native version.

If the native module does not appear in the manifests, double‑check hyperloop.json classes array and rebuild with ti clean first.

Limitations & Checks

• Hyperloop support varies by SDK release; confirm compatibility on the Hyperloop repo before committing.
• Native UI code must be compiled for each architecture (arm64, x86_64). CI pipelines need both macOS and Linux agents.
• Alloy migration is not covered here; if you inherit an Alloy codebase, plan a gradual rewrite to plain Ti.UI or native modules.